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 using the xDG API.

Overview

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

  • The URI of the API.

  • 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 formats

You can choose between two JSON formats when emitting metrics: the single metric format, or a metrics array. The metrics array is the recommended format.

The single metric format is deprecated in favor of the multiple metrics format. The valueType field is not supported in the single metrics format.

Single metrics format

The single metric format has the following JSON structure:

{
    "timestamp" : "<timestamp>", (1)
    "name": "<metricName>", (2)
    "value" : "<metricValue>" (3)
}
1 Metric timestamp, in ISO 8601 format: yyyy-MM-ddTHH:mm:ss.SSSZ. When no timestamp is provided, the current server timestamp is used.
2 Metric name.
3 Metric value. May be text, numeric or a boolean.

Multiple metrics array

The JSON metrics array can hold one or more metrics, as individual JSON objects. You must then 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 that holds multiple metrics.

A full data structure may look like this:

{
    "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 multiple 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>], (6)
}'
Example 2. Template: emit a single metric 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)
    "name": "<metricName>", (4)
    "value" : "<metricValue>" (5)
}'
Example 3. 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>' \ (7)
--header 'Authorization: Bearer <your-personal-access-token>' \ (2)
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 Metric name, such as QualityScore.
5 Metric value. This value is passed as a string, and may be a numeric or string value (such as a badge code).
6 JSON metrics array. Each array object contains two or three fields: a name, a value, and an optional valueType type for each array metric. For more about valueType see the Metrics format section.
7 URL with your tenant name (<your-tenant-name>), an asset URN (<asset_urn>) to get metrics history from, and from and to query parameters with timestamp to define the history range. If to is not provided, the current timestamp is used. If from is not provided, January 1, 1970, 00:00:00 UTC is used.

Metric concatenation

When you emit multiple metrics, the recent metrics are added to the previous ones if they share a timestamp, 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 4. 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 5. 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 6. Emit a single metric 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 '{
    "timestamp" : "2024-03-04T17:44:00.000Z",
    "name": "apiForConsumersNbApiDailyConsumptionCalls",
    "value" : "50"
}'
Example 7. Emit a single metric on an asset - Response example
{
    "timestamp" : "2024-03-04T17:44:00.000Z",
    "name": "apiForConsumersNbApiDailyConsumptionCalls",
    "value" : "50"
    "metrics": null
}
Example 8. 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 9. 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"
}]