Metrics API - GET metric data points

Gets data points of the specified metrics.

You can receive either one aggregated data point per series or a list of data points per series. See the description of the resolution parameter of the request for more information.

The following limits apply:

  • The number of aggregated data points in the response is limited to 1,000
  • The number of series in the response is limited to 1,000
    • The number of data points per series is limited to 10,080
    • The overall number of data points is limited to 100,000

The request produces an application/json payload.

This request is an early adopter release and may be changed in non compatible way.

GET
  • Managed https://{your-domain}/e/{your-environment-id}/api/v2/metrics/series/{selector}
  • SaaS https://{your-environment-id}.live.dexp.ae/api/v2/metrics/series/{selector}

Parameters

Parameter Type Description In Required
selector string

Selects metrics for the query by their keys. You can select up to 10 metrics for one query.

You can specify multiple metric keys separated by commas. For example: metrickey1,metrickey2.

To select multiple metrics belonging to the same parent, you can use a this shorthand: list the last part of the required metric keys in parentheses, separated by commas, while keeping the common part untouched. For example, to list the builtin:host.cpu.idle and builtin:host.cpu.user metric, you could write: builtin:host.cpu.(idle,user).

You can set additional transformation operators, separated by a colon (:). See the Metrics API - selector transformations help page for additional information on available result transformations.

The length of the selector string is limited to 1,000 characters.

 path required
nextPageKey string

Continuation token obtained from nextPageKey in the response payload or from the response header Next-Page-Key to access the next page in a paged result. Mutually exclusive with all other query parameters.

 query optional
pageSize integer

Preferred amount of primary entities for which data is delivered in a single response payload.

 query optional
resolution string

You can use one of the following options:

  • One aggregated data point of each series. Set Inf to use this option.
  • The desired amount of data points. This is the default option. This is a reference number of points, which is not necessarily equals to the number of the returned data points.
  • The timespan between data points. To use this option, specify the unit of the timespan.

Valid units for the timespan are:

  • m: minutes
  • h: hours
  • d: days
  • w: weeks
  • M: months
  • y: years

If not set, the default is 120 data points.

 query optional
from string

The start of the requested timeframe.

You can use one of the following formats:

  • Timestamp in UTC milliseconds
  • Human-readable format of 2019-12-21T05:57:01.123+01:00. If no time zone is specified, UTC is used. You can use a space character instead of the T. Note that seconds and fractions of a second are optional, as the result data is provided with minute accuracy.
  • Relative timeframe, back from now. The format is now-NU/A, where N is the amount of time, U is the unit of time, and A is an alignment. For example, now-1y/w is one year back, aligned by a week. The alignment rounds to the past. Supported time units for the relative timeframe are:
  • m: minutes
  • h: hours
  • d: days
  • w: weeks
  • M: months
  • y: years

If not set, the relative timeframe of two weeks from now is used (now-2w).

 query optional
to string

The end of the requested timeframe.

You can use one of the following formats:

  • Timestamp in UTC milliseconds
  • Human-readable format of 2019-12-21T05:57:01.123+01:00. If no time zone is specified, UTC is used. You can use a space character instead of the T. Note that seconds and fractions of a second are optional, as the result data is provided with minute accuracy.
  • Relative timeframe, back from now. The format is now-NU/A, where N is the amount of time, U is the unit of time, and A is an alignment. For example, now-1y/w is one year back, aligned by a week. The alignment rounds to the past. Supported time units for the relative timeframe are:
  • m: minutes
  • h: hours
  • d: days
  • w: weeks
  • M: months
  • y: years

If not set, the current timestamp is used.

 query optional
scope string

Specifies the scope of the query.

You can set one or several of the following criteria:

  • Tag: tag(value)
  • Management zone name: mz(value)
  • Management zone ID: mzid(value)
  • Entity name: entity(value1,value2). You can specify several entities, separated by a comma (,).
  • DESK entity ID: entity(value1,value2). You can specify several entities, separated by a comma (,).

To set several criteria, separate them with a comma (,). Only results, matching all criteria, are included into response.

The scope is limited to 10,000 entities. If your scope exceeds 10,000 entities, split it into several queries.

You can't use dimensions in the scope. You can, however, use the filter transformation operator on the metric selector. See the Metrics API - selector transformations help page for additional information on available transformation operators.

To set a universal scope, matching all entities, omit this parameter.

The length of the selector string is limited to 1,000 characters.

 query optional

Response format

The MetricSeriesMap object

A list of metrics and their data points.

Element Type Description
totalCount integer

Pagination: Total number of involved primary entities being paged over. If none of the requested metrics is suitable for paging, this is set to zero.
nextPageKey string

Pagination: Continuation token for use with query parameter of same name to obtain next page of results. null on last page.
metrics object

A list of metrics and their data points.

The content depends on the resolution you set in the query:

  • If you used the Inf value for a single data point, it contains the values array.
  • If you used other options (amount of data points of a time step), it contains the series array.
warnings string[]

Additional notes about the result, useful for debugging.

The MetricResult object

A list of metric and their data points.

The content depends on the resolution you set in the query:

  • If you used the Inf value for a single data point it contains the values array.
  • If you used other options (amount of data points of a time step), it contains the series array.
Element Type Description
series MetricSeries[]

The list of metric series and the data points of each series.

A series is a metric per dimension (a unique combination of metric and dimension).
values MetricValue[]

The list of aggregated data points for the metric.

Each data point is an object, containing the timestamp of the data point, the data point value, and the dimension to which the data point belongs.
entityMeta MetricEntityMeta

The MetricEntityMeta object

Element Type Description
name object

The MetricValue object

An aggregated data point of a metric series.

Element Type Description
dimensions string[]

The ordered list of dimension to which the data point belongs.

Each metric can have a certain number of dimensions. Dimensions exceeding this number are aggregated into one, which is shown as null here.
timestamp integer

The end timestamp of the data point, in UTC milliseconds.
value number

The value of the aggregated data point.

The MetricSeries object

The list of metric series along with their data points.

A series is a metric per dimension (a unique combination of metric and dimension).

Element Type Description
dimensions string[]

The ordered list of dimensions to which the data point belongs.

Each metric can have a certain number of dimensions. Dimensions exceeding this number are aggregated into one, which is shown as null here.
values MetricTimestampedValue[]

The ordered list of data points.

The MetricTimestampedValue object

A data point of a metric series.

Element Type Description
timestamp integer

The end timestamp of the data point, in UTC milliseconds.
value number

The value of the data point.

Timeframe note

DESK stores data in time slots. The MetricValue object shows the ending timestamp of the slot. If the time, set in the from or to parameters of your query, falls within the data time slot, this time slot is included in the response.

If the timestamp of the last data slot lays outside of the specified timeframe, the last data point of the response has a later timestamp than the specified in to query parameter.

DESK does not predict future data. The timestamp of the last data point may lay in the future, due to data slots principle, described above. In this case, this data slot has incomplete data.

Timeslot scheme

Examples

In these examples, the requests query the data points of the builtin:host.cpu.usage and builtin:host.cpu.idle metrics. The scope is limited to the management zone with the ID of 9130632296508575249. The timeframe is not specified, so the default timeframe of 2 weeks back from now is used.

The API token is passed in the Authorization header.

The difference between the queries is the representation of data—the first shows the list of data points, while the second shows just one aggregated data point for each series.

The result is truncated to two series per metric and three data points per series for the list of data points.

Curl

curl -X GET \
  'https://mySampleEnv.live.dexp.ae/api/v2/metrics/series/builtin:host.cpu.%28usage,idle%29?scope=mzid%289130632296508575249%29&resolution=100' \
  -H 'Authorization: Api-Token abcdefjhij1234567890'

Request URL

https://mySampleEnv.live.dexp.ae/api/v2/metrics/series/builtin:host.cpu.%28usage,idle%29?scope=mzid%289130632296508575249%29&resolution=100

Response body

{
  "metrics": {
    "builtin:host.cpu.usage": {
      "series": [
        {
          "dimensions": [
            "HOST-661B5DDFE19DB5AE"
          ],
          "values": [
            {
              "timestamp": 1559563200000,
              "value": 0.7537290219907408
            },
            {
              "timestamp": 1559574000000,
              "value": 0.6646773726851852
            },
            {
              "timestamp": 1559584800000,
              "value": 0.6338252314814815
            }
          ]
        },
        {
          "dimensions": [
            "HOST-7CF622A2AB0AFFD3"
          ],
          "values": [
            {
              "timestamp": 1559563200000,
              "value": 2.614283130787037
            },
            {
              "timestamp": 1559574000000,
              "value": 2.5198640046296297
            },
            {
              "timestamp": 1559584800000,
              "value": 2.3291558159722223
            }
          ]
        }
      ]
    },
    "builtin:host.cpu.idle": {
      "series": [
        {
          "dimensions": [
            "HOST-661B5DDFE19DB5AE"
          ],
          "values": [
            {
              "timestamp": 1559563200000,
              "value": 99.24627097800926
            },
            {
              "timestamp": 1559574000000,
              "value": 99.33532262731481
            },
            {
              "timestamp": 1559584800000,
              "value": 99.36617476851852
            }
          ]
        },
        {
          "dimensions": [
            "HOST-7CF622A2AB0AFFD3"
          ],
          "values": [
            {
              "timestamp": 1559563200000,
              "value": 97.38571686921296
            },
            {
              "timestamp": 1559574000000,
              "value": 97.48013599537038
            },
            {
              "timestamp": 1559584800000,
              "value": 97.67084418402777
            }
          ]
        }
      ]
    }
  }
}

Response code

200