Emit Metrics and Badges

Overview

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" : "<metric-value>" (5)
}'
the "single metric" format is now deprecated in favor of the multiple metrics format. The valueType field will not be supported.
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 The URL contains your tenant name (<your-tenant-name>) as well as the URN of the asset (<asset_urn>) on which you want to emit the metric.
2 The authentication is performed using a personal access token.
3 The metric timestamp. It is the time in ISO 8601 format : <yyyy-MM-ddTHH:mm:ss.SSSZ>. When the timestamp is not provided, the current server timestamp is used.
4 The metric name, for example: "QualityScore".
5 The metric value. Note that it is passed as a string, and this value may be a numeric or string value (for example, a badge code).
6 The JSON metrics array : each object from the array contains 2 to 3 fields : name, value and the optional valueType type for each metric of the array (see the Metrics Format section for more details on valueType).
7 The URL contains your tenant name (<your-tenant-name>) as well as the URN of the asset (<asset_urn>) on which you get metrics history with "from" and "to" parameters to get a range of timestamps to get the metrics. If "to" is not provided, the current timestamp is used. If from is not provided, January 1, 1970, 00:00:00 UTC is used.
We have Two ways to emit metrics : with a metrics array , or a single metrics. In any case the metric emission will add the new metrics to existing metrics within the same timestamp. For example, for the same timestamp, if we send first [A, B, C] then [B, C, D] B and C will be updated and D added.

Metrics Format

To emit multiple metrics, an array of metrics must be given. The format of those metrics is as follow:

{
    "name" : "isActiveInLast24Hours", (1)
    "value" : true, (2)
    "valueType" : "BOOLEAN" (3)
}
1 the name of the metric
2 the value of the metric. May be text, numeric or boolean (see exemples)
3 (optional) the type of the value. The following values are accepted: STRING, NUMBER and BOOLEAN. If absent, it will be guessed.
if the valueType is given and doesn’t match the value (ex: value is 18 and valueType is BOOLEAN), the API will return an error and a 400 status code
the valueType field is not supported on the Emit a single metric endpoint

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"
}]