Metrics API - GET metric descriptor

Gets the parameters of the specified metric.

The request produces one of the following types of payload, depending on the value of the the Accept request header:

application/json
text/csv; header=present—a CSV table with header row
text/csv; header=absent—a CSV table without header row

If no Accept header is provided with the request, an application/json payload is returned.

GET	Managed https://{your-domain}/e/{your-environment-id}/api/v2/metrics/{metricId} SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/{metricId}

Authentication

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

Parameters

Parameter Type Description In Required

metricId

string

Parameter	Type	Description	In	Required
metricId	string	The key of the required metric. 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 string is limited to 1,000 characters.	path	required

The key of the required metric.

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 string is limited to 1,000 characters.

path

required

Response format

Response parameters JSON model

The MetricDescriptor object

The descriptor of a metric.

Element	Type	Description
aggregationTypes	string[]	The list of allowed aggregations for this metric.
metricId	string	The fully qualified key of the metric. If a transformation has been used it is reflected in the metric key.
entityType	string[]	List of admissible primary entity types for this metric. Can be used for the `type` predicate in the `entitySelector`.
dimensionDefinitions	MetricDimensionDefinition[]	The fine metric division (for example, process group and process ID for some process-related metric).
defaultAggregation	MetricDefaultAggregation
description	string	A short description of the metric.
transformations	string[]	Transform operators that could be appended to the current transformation list. Must be enabled with the "fields" parameter on `/metrics` and is always present on `/metrics/{metricId}`.
unit	string	The unit of the metric.
displayName	string	The name of the metric in the user interface.

The MetricDefaultAggregation object

The default aggregation of a metric.

Element Type Description

parameter

number

Element	Type	Description
parameter	number	The percentile to be delivered. Valid values are between `0` and `100`. Applicable only to the `percentile` aggregation type.
type	string	The type of default aggregation.

The percentile to be delivered. Valid values are between 0 and 100.

Applicable only to the percentile aggregation type.

type

string

The type of default aggregation.

The MetricDimensionDefinition object

The dimension of a metric.

Element	Type	Description
index	integer	The unique 0-based index of the dimension. Appending transformations such as :names or :parents may change the indexes of dimensions.
name	string	The name of the dimension.
key	string	The key of the dimension. It must be unique within the metric.
type	string	The type of the dimension.

    
{
  "metricId": "builtin:host.cpu.user:merge(0):max:fold",
  "displayName": "CPU user",
  "description": "Percentage of user-space CPU time currently utilized, per host.\n",
  "unit": "Percent",
  "aggregationTypes": [
    "auto",
    "avg",
    "max",
    "min"
  ],
  "transformations": [
    "fold"
  ],
  "defaultAggregation": {
    "type": "avg"
  },
  "dimensionDefinitions": [
    {
      "name": "primary",
      "type": "ENTITY"
    }
  ],
  "entityType": [
    "HOST"
  ]
}

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

The response is in application/json format.

Curl

curl -L -X GET 'https://mySampleEnv.live.dynatrace.com/api/v2/metrics/builtin:host.disk.avail' \
-H 'Authorization: Api-Token abcdefjhij1234567890' \
-H 'Accept: application/json'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/metrics/builtin:host.disk.avail

Response body

{
  "metricId": "builtin:host.disk.avail",
  "displayName": "Disk available",
  "description": "",
  "unit": "Byte",
  "entityType": [
    "HOST"
  ],
  "aggregationTypes": [
    "auto",
    "avg",
    "max",
    "min"
  ],
  "transformations": [
    "filter",
    "fold",
    "merge",
    "names",
    "parents"
  ],
  "defaultAggregation": {
    "type": "avg"
  },
  "dimensionDefinitions": [
    {
      "key": "dt.entity.host",
      "name": "Host",
      "index": 0,
      "type": "ENTITY"
    },
    {
      "key": "dt.entity.disk",
      "name": "Disk",
      "index": 1,
      "type": "ENTITY"
    }
  ]
}

The CSV table with header row looks like this. To obtain it, change the Accept header to text/csv; header=present.

metricId,displayName,description,unit,entityType,aggregationTypes,transformations,defaultAggregation,dimensionDefinitions
builtin:host.cpu.usage,CPU usage %,Percentage of CPU time currently utilized.,Percent,[HOST],"[auto, avg, max, min]","[filter, fold, merge, names, parents]",avg,[Host:ENTITY]

Response code

200