Version: v4.6

Metrics Service API Overview

Services which currently support metrics#

The Metrics Service API calls are generally grouped according to the back-end services which support metrics information. Currently, metrics are available for the following three back-end services:

Click on any of the services listed above for detailed information on their Metrics Service API calls.

Metrics Service Endpoints#

There are two forms of endpoints available for each metric:

Endpoints which return all known values for a given metric
Endpoints which return all values for a given metric, for a particular time period

Endpoints which returns all known values for a given metric#

These are general Metric Service calls and the endpoints generally take the form of:

GET /metricsvc/api/v1/metrics/{metric name}?{dimensions}

Note: All endpoint calls must specify at least one dimension, at least the namespace.

Endpoints which returns all values for a given metric, for a particular period#

These are Metrics Service calls with period parameters and the endpoints generally take the form of:

GET /metricsvc/api/v1/metrics/{metric name}/by-dimension;{dimensions}?{period parameters}

If you do not specify period parameters for this endpoint, it will default to a time period of the last seven days.

Note For this form of URL, multi-level dimensions should be separated by ;. For example, dimensions could be namespace=digitaltwin_883WeSED;collection_id=tempsensor_bvsl3jVm79

Metrics Service calls with period parameters#

There are period parameters available which can be used to filter certain metrics based on time and duration.

Period parameters can be applied to metrics which have an endpoint format which specifies a period of time, such as the example below:
GET /metricsvc/api/v1/metrics/{metric name}/by-dimension;{dimensions}?{period parameters}

Note: Period parameters cannot be applied to general Metrics Service calls (returns all values for a given metric) which have an endpoint format such as: GET /metricsvc/api/v1/metrics/{metric name}?{dimensions}

Types of period parameters#

The three period parameters are:

period.relative
period.from
period.to

Relative period#

The default parameter is period.relative=P7D. This specifies a relative period of seven days preceeding the current time.

The relative period format can use Java’s Period or Duration formats, which are based on the ISO 8601 standard. For more information visit ISO 8601.

Note: Periods containing years or months cannot also contain hours, minutes, or seconds.

Example of relative period usage#

The example below shows a Metrics Service API call for the File Service, which returns the file version sizes (in bytes) for the name space digitaltwin_xyz for a period of one year preceeding the current time.

Request:

GET /metricsvc/api/v1/metrics/dtplatform.filesvc.FileVersionSize/by-dimension;namespace=digitaltwin_xyz?period.relative=P1Y

Response:

{    "metricName": "dtplatform.filesvc.FileVersionSize",    "dimensions": {        "namespace": "digitaltwin_xyz"    },    "metrics": [        {            "timestamp": "2024-03-22T08:00:00Z",            "value": 656        },        {            "timestamp": "2024-06-24T00:00:00Z",            "value": 9636        },        {            "timestamp": "2024-07-24T00:00:00Z",            "value": 18616        }    ]}

Period.from and period.to#

The period.from and period.to parameters can be used to specify a fixed period in time. They take a date in ISO-8601 format. For example, 2023-12-17T00:00:00Z.

Combining period parameters#

If period.relative and period.to are both provided, the date filtering is defined as the specified time period prior to the specified end date.

For example, period.relative=P7D&period.to=2023-12-17T00:00:00Z specifies the seven day period up to 17th December 2023 (UTC). If all three parameters are specified, the date filtering is based on the fixed period between period.from and period.to and period.relative is ignored.

Example of relative period to specified date#

The example below shows an API call for the FileVersionSize metric for the File Service, for the namespace: digitaltwin_xyz, for a relative period of two days prior to the date: 2024-07-25.

Request:

GET /metricsvc/api/v1/metrics/dtplatform.filesvc.FileVersionSize/by-dimension;namespace=digitaltwin_xyz?period.relative=P2D&period.to=2024-07-25T00:00:00Z

Response:

{    "metricName": "dtplatform.filesvc.FileVersionSize",    "dimensions": {        "namespace": "digitaltwin_zyz"    },    "metrics": [        {            "timestamp": "2024-07-23T00:00:00Z",            "value": 9636        },        {            "timestamp": "2024-07-24T00:00:00Z",            "value": 18616        }    ]}

General Metrics Service calls and metadata requests#

General Metrics Service API calls are requests which are not exclusive to any service and return all the available metrics for, say a particular namespace. They are useful for performing metadata requests.

The example format of such an API call is listed below.

GET /metricsvc/api/v1/metrics?{dimensions}

Example of general metric usage#

The example API call below returns all the available metrics for the name space digitaltwin_xyz and the file_id: 7061b39a-1527-4e53-8c98-70412e14a835.

Request:

GET /metricsvc/api/v1/metrics?namespace=digitaltwin_xyz&file_id=7061b39a-1527-4e53-8c98-70412e14a835

Response:

{    "metrics": [        {            "metricName": "dtplatform.filesvc.FileVersionCount",            "dimensions": {                "file_id": "7061b39a-1527-4e53-8c98-70412e14a835",                "namespace": "digitaltwin_xyz"            },            "value": 1        },        {            "metricName": "dtplatform.filesvc.FileVersionSize",            "dimensions": {                "file_id": "7061b39a-1527-4e53-8c98-70412e14a835",                "namespace": "digitaltwin_xyz"            },            "value": 27314        }    ]}

Example of metadata request#

A metadata request returns all the metrics with all the combinations of dimensions that are available. The response will not include any actual values. You might use this request if you were unsure as to the metric name or what dimensions are available.

For example, the request below will return all metric names and associated dimensions for the namespace digitaltwin_xyz.

Request:

GET /metricsvc/api/v1/metrics/metadata?nsfilter=digitaltwin_xyz

Response:

Note The example response shown below is truncated as the entire response is too long to include.


{  "metrics": [    {      "metricName": "dtplatform.itemsvc.NamedFileCollectionVersionSize",      "dimensions": {        "collection": "atm def collection_4TbaRhpk9K",        "namespace": "digitaltwin_xyz"      }    },    {      "metricName": "dtplatform.filesvc.FileVersionSize",      "dimensions": {        "file_id": "12497fe5-7f06-4b6a-b2c8-f75f49bcde04",        "namespace": "digitaltwin_xyz",        "version": "9"      }    },    {      "metricName": "dtplatform.filesvc.PreviewImageFileSize",      "dimensions": {        "file_id": "fbc35dfe-dfbc-4b2b-9cd9-7c1cafcd041c",        "namespace": "digitaltwin_xyz",        "version": "3"      }    },    {      "metricName": "dtplatform.itemsvc.NamedUserCollectionVersionSize",      "dimensions": {        "collection": "testshortname_0_Qube5PoN5i",        "namespace": "digitaltwin_xyz",        "version": "1"      }    },    {      "metricName": "dtplatform.itemsvc.NamedUserCollectionVersionSize",      "dimensions": {        "collection": "testshortname__gh89rLAAw6",        "namespace": "digitaltwin_xyz"      }    },    {      "metricName": "dtplatform.itemsvc.NamedUserCollectionVersionSize",      "dimensions": {        "namespace": "digitaltwin_xyz"      }    }  .....
  ]}