Metrics API - GET metric descriptors

Gets the parameters of the specified metrics. You can select up to 10 metrics.

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/descriptors/{selector}
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/descriptors/{selector}

Authentication

To execute this request, you need the Access problem and event feed, metrics, and topology permission assigned to your API token. See the Authentication page to learn how to obtain and use it.

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).

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

path required

Response format

The MetricDescriptorMap object

A list of metrics and their descriptors.

Element Type Description
metrics object

A list of metrics and their descriptors.

The MetricDescriptor object

The descriptor of a metric.

Element Type Description
meta MetricMeta

Parameters of the metric.

The MetricMeta object

The descriptor of a metric.

Element Type Description
metricKey string

The fully qualified key of the metric.

displayName string

The name of the metric in the user interface.

description string

A short description of the metric.

unit string

The unit of the metric.

aggregationTypes string[]

The list of allowed aggregations for this metric.

defaultAggregation MetricStatistic

The default aggregation of the metric.

It is always used if you don't specify the desired aggregation.

dimensionDefinitions MetricDimensionDefinition[]

The fine metric division, for example, process group and process ID for some process-related metric.

The MetricDimensionDefinition object

The dimension of a metric.

Element Type Description
name string

The name of the dimension.

It must be unique within the metric.

type string

The type of the dimension.

The MetricStatistic object

The default aggregation of a metric.

Element Type Description
type string

The type of default aggregation.

parameter number

Specified which percentile of the metric should be delivered.

Applicable only to the PERCENTILE aggregation type.

Valid values for percentile are between 0 and 100.

Example

In this example, the request queries the parameters of three metrics: builtin:host.cpu.idle, builtin:host.cpu.usage, and builtin:host.disk.avail.

The builtin:host.cpu.idle and builtin:host.cpu.usage metrics have the same parent and their selector is combined into builtin:host.cpu.(idle,usage).

Curl

curl -X GET \
  'https://mySampleEnv.live.dynatrace.com/api/v2/metrics/descriptors/builtin:host.cpu.%28idle,usage%29,builtin:host.disk.avail' \
  -H 'Authorization: Api-Token abcdefjhij1234567890'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/metrics/descriptors/descriptors/builtin:host.cpu.(idle,usage),builtin:host.disk.avail

Response body

{
  "metrics": {
    "builtin:host.cpu.idle": {
      "meta": {
        "metricKey": "builtin:host.cpu.idle",
        "displayName": "CPU idle",
        "description": "",
        "unit": "Percent",
        "aggregationTypes": [
          "AVG",
          "MAX",
          "MIN"
        ],
        "defaultAggregation": {
          "type": "AVG"
        },
        "dimensionDefinitions": [
          {
            "name": "primary",
            "type": "ENTITY"
          }
        ]
      }
    },
    "builtin:host.cpu.usage": {
      "meta": {
        "metricKey": "builtin:host.cpu.usage",
        "displayName": "CPU usage",
        "description": "Percentage of CPU time currently utilized.",
        "unit": "Percent",
        "aggregationTypes": [
          "AVG",
          "MAX",
          "MIN"
        ],
        "defaultAggregation": {
          "type": "AVG"
        },
        "dimensionDefinitions": [
          {
            "name": "primary",
            "type": "ENTITY"
          }
        ]
      }
    },
    "builtin:host.disk.avail": {
      "meta": {
        "metricKey": "builtin:host.disk.avail",
        "displayName": "Disk available ",
        "description": "",
        "unit": "Byte",
        "aggregationTypes": [
          "AVG",
          "MAX",
          "MIN"
        ],
        "defaultAggregation": {
          "type": "AVG"
        },
        "dimensionDefinitions": [
          {
            "name": "primary",
            "type": "ENTITY"
          },
          {
            "name": "rx_disk",
            "type": "ENTITY"
          }
        ]
      }
    }
  }
}

Response code

200