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