This documentation and the Cisco Observability Platform functionalities it describes are subject to change. Data saved on the platform may disappear and APIs may change without notice.
Platform Functions
The platform functions are predefined functions provided by Cisco Codex that enable you to perform complex processing or platform-specific processing such as generating entity ID, which otherwise are not possible by using the JSONata functions. You can use these platform functions by referring them directly in your Codex workflows. These functions run natively as a part of the workflow runtime.
You can use a platform function:
- as an inline expression in
JSONataexpression - as a custom function type
Note: Some platform functions can be used only as inline expression in
JSONataexpression.
Supported Functions
The following section describes the platform functions provided by Codex:
createEntity
The function creates or assigns an entity of a given type. Codex validates if all the required attributes are provided for a given input entity type. The function generates an entity ID if not already present. The following attributes are required to create an entity:
entityType(fully qualified type name)attributes
Input Schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "classpath:/json-schemas/types/createEntity.json",
"title": "createEntity",
"description": "create entity",
"type": "object",
"required": ["entityType", "attributes"],
"properties": {
"entityType": {
"type": "string",
"description": "A type name that is unique within this namespace.",
"pattern": "^[a-z]+[a-z0-9_]{0,64}:[a-z]+[a-z0-9_.]{0,256}[^._]$",
"examples": ["k8s:pod", "infra:container"]
},
"attributes": {
"$ref": "#/definitions/anyValueMap"
},
"tags": {
"$ref": "#/definitions/Tags"
},
"additionalProperties": false
},
"definitions": {
"anyValueMap": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/definitions/anyValue"
}
},
"anyValue": {
"type": [
"object",
"null"
],
"properties": {
"value": {
"$ref": "#/definitions/dataTypes"
}
},
"additionalProperties": false
},
"Tags" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
},
"dataTypes": {
"oneOf": [{
"type": [
"string",
"null",
"number",
"integer",
"boolean"
]
},
{
"type": "array",
"items": {
"$ref": "#/definitions/anyValue"
}
},
{
"$ref": "#/definitions/anyValueMap"
}
]
}
}
}
Input Example:
{
"entityType": "k8s:pod",
"attributes": {
"key1": {
"value": "value1"
},
"key2": {
"value": "value2"
}
}
}
Output Schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "classpath:/json-schemas/types/entityId.json",
"title": "entity",
"description": "Output contract for created entity by platform function.",
"type": "object",
"required": ["id", "observedAt", "entityType", "source", "attributes"],
"properties": {
"id": {
"type": "string",
"description": "The unique entity id.",
"examples": ["mOp9soJVQauNpshW+BBGmA"]
},
"observedAt": {
"type": "number",
"description": "The epoch time in nanos when this entity is observed."
},
"entityType": {
"type": "string",
"description": "A type name that is unique within this namespace.",
"pattern": "^[a-z]+[a-z0-9_]{0,64}:[a-z]+[a-z0-9_.]{0,256}[^._]$",
"examples": ["k8s:pod", "infra:container"]
},
"attributes": {
"$ref": "#/definitions/anyValueMap"
},
"source": {
"type": "string",
"const": "sys:derived"
},
"additionalProperties": false
},
"definitions": {
"anyValueMap": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/definitions/anyValue"
}
},
"anyValue": {
"type": [
"object",
"null"
],
"properties": {
"value": {
"$ref": "#/definitions/dataTypes"
}
},
"additionalProperties": false
},
"dataTypes": {
"oneOf": [{
"type": [
"string",
"null",
"number",
"integer",
"boolean"
]
},
{
"type": "array",
"items": {
"$ref": "#/definitions/anyValue"
}
},
{
"$ref": "#/definitions/anyValueMap"
}
]
}
}
}
Output Example:
{
"id": "mOp9soJVQauNpshW+BBGmA",
"observedAt": 1679315872000000000,
"entityType": "infra:container",
"source": "sys:derived",
"attributes": {
"key1": {
"value": "value1"
},
"key2": {
"value": "value2"
}
}
}
How to Use the Function in Workflows
The createEntity function can be used in your Codex workflows in one of the following ways:
- Inline expression in JSONata expression
- Custom function
Inline Expression in JSONata
The following example illustrates the function definition:
{
"name": "createEntity",
"type": "expression",
"operation": "$createEntity({ \"entityType\": groupedSpans[0].spans[0].entities[0].type, \"attributes\": {\"k8s.cluster.id\": \"trace2evenrawmentity\", \"codextext\": \"trace2evenrawmentity\", \"workflow\": \"trace to event workflow with rawm and entity creation\" } })"
}
The following examples illustrate the usage of the function definition of the type expression in a Codex workflow:
{
"id": "trace2evenrawmentity",
"version": "1.0",
"specVersion": "0.8",
"name": "trace2evenrawmentity",
"description": "trace to event workflow with rawm and entity creation",
"expressionLang": "Jsonata",
"start": "ReadTrace",
"events": [
{
"name": "TraceReceived",
"type": "contracts:cloudevent/platform:trace.enriched.v1",
"source": "platform",
"kind": "consumed"
},
{
"name": "EventCreated",
"type": "contracts:cloudevent/platform:event.received.v1",
"source": "platform",
"kind": "produced"
},
{
"name": "EntityObserved",
"type" : "contracts:cloudevent/platform:entity.observed.v1",
"kind": "produced"
},
{
"name": "RawMeasurementCreated",
"type": "contracts:cloudevent/platform:measurement.received.v1",
"source": "platform",
"kind": "produced"
}
],
"functions": [
{
"name": "generateEvents",
"type": "expression",
"operation": "{\"event\" :groupedSpans[0].spans.{\"entities\" : entities, \"type\": \"k8s:native_event\", \"timestamp\" : startedAt, \"raw\":\"trace to event workflow with rawm and entity creation\", \"spanId\": \"\", \"traceId\": \"\", \"attributes\": {\"severity\": \"DEBUG\", \"workflow\":\"trace2evenrawmentity\", \"appd.isevent\": True } }}"
},
{
"name": "createEntity",
"type": "expression",
"operation": "$createEntity({ \"entityType\": groupedSpans[0].spans[0].entities[0].type, \"attributes\": {\"k8s.cluster.id\": \"trace2evenrawmentity\", \"codextext\": \"trace2evenrawmentity\", \"workflow\": \"trace to event workflow with rawm and entity creation\" } })"
},
{
"name": "generateRawMeasurement",
"type": "expression",
"operation": "{ \"metric\": {\"entity\": groupedSpans[0].spans[0].entities[0], \"type\": \"codexqe:codexmetric\", \"attributes\": {\"workflow\":\"trace2evenrawmentity\"}, \"measurements\": [ { \"timestamp\": groupedSpans[0].spans[0].startedAt, \"intValue\": 1 }] } }"
}
],
"states": [
{
"name": "ReadTrace",
"type": "event",
"onEvents": [
{
"eventRefs": [
"TraceReceived"
],
"eventDataFilter": {
"data": "${ data }"
}
}
],
"transition": "CreateEvent"
},
{
"name": "CreateEvent",
"type": "operation",
"actions": [
{
"functionRef": {
"refName": "generateEvents"
}
},
{
"functionRef": {
"refName": "createEntity"
},
"actionDataFilter": {
"toStateData": "${ myEntity }"
}
},
{
"functionRef": {
"refName": "generateRawMeasurement"
}
}
],
"end": {
"terminate": true,
"produceEvents": [
{
"eventRef": "EventCreated",
"data": "${ event }"
},
{
"eventRef": "EntityObserved",
"data": "${ myEntity }"
},
{
"eventRef": "RawMeasurementCreated",
"data": "${ metric }"
}
]
}
}
]
}
Custom function
The following example illustrates the function definition:
{
"name": "createEntity",
"type": "custom",
"operation": "createEntity"
}
The following examples illustrate the usage of the function definition of the type custom in a Codex workflow:
{
"id": "MetricToEntity",
"version": "1.0",
"specVersion": "0.8",
"name": "MetricToEntity Workflow",
"description": "Workflow to test custom function with sync action",
"expressionLang": "Jsonata",
"start": "MetricReceived",
"functions": [
{
"name": "createEntity",
"type": "custom",
"operation": "createEntity"
}
],
"events": [
{
"name": "MetricReceived",
"type": "contracts:cloudevent/platform:metric.enriched.v1",
"source": "platform",
"kind": "consumed"
},
{
"name": "EntityObserved",
"type": "contracts:cloudevent/platform:entity.observed.v1",
"source": "platform",
"kind": "produced"
}
],
"states": [
{
"name": "MetricReceived",
"type": "event",
"onEvents": [
{
"eventRefs": [
"MetricReceived"
],
"eventDataFilter": {
"data": "${ data }",
"toStateData": "${ metric }"
}
}
],
"transition": "CreateEntityAndEvent"
},
{
"name": "CreateEntityAndEvent",
"type": "operation",
"actions": [
{
"functionRef": {
"refName": "createEntity"
},
"actionDataFilter": {
"fromStateData": "${ { \"entityType\": metric.entities[0].type, \"attributes\": { \"key1\": \"value1\", \"key2\": \"value2\" } } }",
"toStateData": "${ myEntity }"
}
}
],
"end": {
"terminate": true,
"produceEvents": [
{
"eventRef": "EntityObserved",
"data": "${ myEntity }"
}
]
}
}
]
}