Emit and capture metrics

Semarchy xDG generates metrics while harvesting metatada. You can also explicitly emit metrics to have xDG capture them.

This article explains how to emit metrics to xDG using its REST API.

Overview

Emit metrics to xDG using an HTTP POST request. The request must contain the following elements:

  • The URI of the REST API endpoint.

  • The header Content-Type: application/json.

  • The header Authorization: Bearer with your personal access token.

  • Metrics data in JSON format.

You can also send a GET request to retrieve metrics instead of emitting them.

For templates with explanations, see the templates section of this article.

Data format

Emit metrics as a JSON array that contains one or more metrics as JSON objects. You must encapsulate the array in a higher-level JSON object before sending it.

The lowest-level JSON object has the following structure:

{
    "name" : "<name>", (1)
    "value" : <value>, (2)
    "valueType" : "<type>" (3)
}
1 Metric name.
2 Metric value. May be text, numeric or a boolean.
3 Optionally, the value type. The value may be one of STRING, NUMBER, or BOOLEAN.

The valueType key:value pair has the following interactions:

  • If it is omitted, the value type is automatically guessed.

  • If valueType and value are incompatible, the API returns an error with a 400 status code. For example, a value of 18 and a`valueType` of BOOLEAN do not match.

  • The valueType field is not supported on the endpoint to emit a single metric.

Concatenate the metrics objects into an array:

[
    {<metrics_object>},
    {<metrics_object>}
]

Add the array as the value of the metrics key in a higher-level object. You can also add a timestamp key:value pair.

{
    "timestamp" : "<timestamp>", (1)
    "metrics": [<json-metrics-array>], (2)
}
1 Optional metric timestamp, in ISO 8601 format: yyyy-MM-ddTHH:mm:ss.SSSZ. When no timestamp is provided, the current server timestamp is used.
2 Array containing one or more metrics.

A full data structure may look like this example:

{
    "metrics": [
        {
            "name": "isActiveInLast24Hours",
            "value": true,
            "valueType": "BOOLEAN"
        },
        {
            "name": "data",
            "value": 18
        }
    ],
    "timestamp": "2024-03-02T17:44:00.000Z"
}

Metric naming

To make it easier to work with metrics, use a consistent naming scheme. Camel case is the recommended format.

Templates

Use these templates to build a request to emit or retrieve metrics using the API.

Example 1. Template: emit a set of metrics on an asset
curl -X POST --location 'https://<your-tenant-name>.semarchy.net/api/xdg/v1/asset/<asset_urn>/metric' \ (1)
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-personal-access-token>' \ (2)
--data '{
    "timestamp" : "<timestamp>", (3)
    "metrics": [<json-metrics-array>], (4)
}'
1 URL with your tenant name (<your-tenant-name>), and the asset URN (<asset_urn>) on which you want to emit the metric.
2 Authentication uses a personal access token.
3 Metric timestamp, in ISO 8601 format: yyyy-MM-ddTHH:mm:ss.SSSZ. When no timestamp is provided, the current server timestamp is used.
4 JSON metrics array. Each array object contains two or three fields: a name, a value, and an optional valueType type for each array metric.
Example 2. Template: get metrics on an asset from a range of timestamps
curl --location 'https://<your-tenant-name>.semarchy.net/api/xdg/v1/asset/<asset_urn>/metric?from=<yyyy-MM-ddTHH:mm:ss.SSSZ>&to=<yyyy-MM-ddTHH:mm:ss.SSSZ>' \ (1)
--header 'Authorization: Bearer <your-personal-access-token>' \ (2)
1 URL with your tenant name (<your-tenant-name>), an asset URN (<asset_urn>) to get metrics history from, and optional from and to query parameters with timestamp to define the history range. If not provided, to defaults to the current timestamp, and from defaults to January 1, 1970, 00:00:00 UTC.
2 Authentication uses a personal access token.

Metric concatenation

When you emit multiple metrics, recent metrics that share a timestamp are added to the previous ones, and metrics with the same names are updated.

For example, suppose you send the metrics [A, B, C], then [B, C, D]. If all metrics have the same timestamp, B and C are updated and D is added. Your result looks like [A, B, C, D].

Examples

Example 3. Emit multiple metrics on an asset - Query example
curl -X POST --location 'https://<your-tenant-name>.semarchy.net/api/xdg/v1/asset/<asset_urn>/metric' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-personal-access-token>' \
--data '{
    "metrics" : [
        {
            "name" : "thirdPartyAgentLastExecutionDate",
            "value" : "2024-03-02T17:44:00.000Z"
        },{
            "name" : "thirdPartyAgentNbProcessedRecords",
            "value" : 100,
            "valueType": "NUMBER"
        },{
            "name" : "isActiveInLast24Hours",
            "value" : true,
            "valueType": "BOOLEAN"
        }
    ]
}'
Example 4. Emit multiple metrics on an asset - Response example
{
    "metrics": [
        {
            "name" : "thirdPartyAgentLastExecutionDate",
            "value" : "2024-03-02T17:44:00.000Z",
            "valueType": "STRING"
        },{
            "name" : "thirdPartyAgentNbProcessedRecords",
            "value" : 100,
            "valueType": "NUMBER"
        },{
            "name" : "isActiveInLast24Hours",
            "value" : true,
            "valueType": "BOOLEAN"
        }
    ],
    "name": null,
    "timestamp": "2024-03-04T17:44:00.000Z",
    "value": null
}
Example 5. Get metrics on an asset from a range of timestamps - Query example
curl --location 'https://<your-tenant-name>.semarchy.net/api/xdg/v1/asset/<asset_urn>/metric?from=2024-03-04T17:43:00.000Z&to=2024-03-04T17:45:00.000Z' \
--header 'Authorization: Bearer <your-personal-access-token>'
Example 6. Get metrics on an asset from a range of timestamps - Response example
[{
    "metrics": [
        {
            "name" : "thirdPartyAgentLastExecutionDate",
            "value" : "2024-03-02T17:44:00.000Z",
            "valueType" : "STRING"
        },{
            "name" : "thirdPartyAgentNbProcessedRecords",
            "value" : 100,
            "valueType" : "NUMBER"
        },{
            "name" : "apiForConsumersNbApiDailyConsumptionCalls",
            "value" : 50,
            "valueType" : "NUMBER"
        }
    ],
    "timestamp": "2024-03-04T17:44:00.000Z"
}]