• Home
  • Dynatrace API
  • Environment
  • Metrics v2
  • GET metric descriptor

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

GETManaged https://{your-domain}/e/{your-environment-id}/api/v2/metrics/{metricKey}
SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/{metricKey}
Environment ActiveGate https://{your-activegate-domain}/e/{your-environment-id}/api/v2/metrics/{metricKey}

Authentication

To execute this request, you need an access token with Read metrics (metrics.read) scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

ParameterTypeDescriptionInRequired
metricKeystring

The key of the required metric.

You can set additional transformation operators, separated by a colon (:). See Metrics selector transformations in Dynatrace Documentation for additional information on available result transformations and syntax.

pathrequired

Response

Response codes

CodeTypeDescription
200MetricDescriptor

Success

404-

A metric has not been found.

406-

Not acceptable. The requested media type is not supported. Check the Accept header of your request.

Response body objects

The MetricDescriptor object

The descriptor of a metric.

ElementTypeDescription
tagsstring[]

The tags applied to the metric.

Metric expressions don't return this field.

Can be null.

dduBillableboolean

If true the usage of metric consumes Davis data units.

Metric expressions don't return this field.

Can be null.

dimensionDefinitionsMetricDimensionDefinition[]

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

For ingested metrics, dimensions that doesn't have have any data within the last 15 days are omitted.

Can be null.

maximumValuenumber

The maximum allowed value of the metric.

Metric expressions don't return this field.

Can be null.

latencyinteger

The latency of the metric, in minutes.

The latency is the expected reporting delay (for example, caused by constraints of cloud vendors or other third-party data sources) between the observation of a metric data point and its availability in Dynatrace.

The allowed value range is from 1 to 60 minutes.

Metric expressions don't return this field.

Can be null.

resolutionInfSupportedboolean

If 'true', resolution=Inf can be applied to the metric query.

Can be null.

unitDisplayFormatstring

The raw value is stored in bits or bytes. The user interface can display it in these numeral systems:

Binary: 1 MiB = 1024 KiB = 1,048,576 bytes

Decimal: 1 MB = 1000 kB = 1,000,000 bytes

If not set, the decimal system is used.

Metric expressions don't return this field.

The element can hold these values
  • binary
  • decimal

Can be null.

dimensionCardinalitiesMetricDimensionCardinality[]

The cardinalities of MINT metric dimensions.

Can be null.

defaultAggregationMetricDefaultAggregation

The default aggregation of a metric.

Can be null.

lastWritteninteger

The timestamp when the metric was last written.

Has the value of null for metric expressions or if the data has never been written.

Can be null.

rootCauseRelevantboolean

The metric is (true) or is not (false) root cause relevant.

A root-cause relevant metric represents a strong indicator for a faulty component.

Metric expressions don't return this field.

Can be null.

impactRelevantboolean

The metric is (true) or is not (false) impact relevant.

An impact-relevant metric is highly dependent on other metrics and changes because an underlying root-cause metric has changed.

Metric expressions don't return this field.

Can be null.

minimumValuenumber

The minimum allowed value of the metric.

Metric expressions don't return this field.

Can be null.

entityTypestring[]

List of admissible primary entity types for this metric. Can be used for the type predicate in the entitySelector.

Can be null.

metricIdstring

The fully qualified key of the metric.

If a transformation has been used it is reflected in the metric key.

metricSelectorstring

The metric selector that is used when querying a func: metric.

Can be null.

aggregationTypesstring[]

The list of allowed aggregations for this metric.

The element can hold these values
  • auto
  • avg
  • count
  • max
  • median
  • min
  • percentile
  • sum
  • value

Can be null.

scalarboolean

Indicates whether the metric expression resolves to a scalar (true) or to a series (false). A scalar result always contains one data point. The amount of data points in a series result depends on the resolution you're using.

Can be null.

metricValueTypeMetricValueType

The value type for the metric.

Can be null.

displayNamestring

The name of the metric in the user interface.

Can be null.

descriptionstring

A short description of the metric.

Can be null.

transformationsstring[]

Transform operators that could be appended to the current transformation list.

The element can hold these values
  • asGauge
  • default
  • delta
  • evaluateModel
  • filter
  • fold
  • last
  • lastReal
  • limit
  • merge
  • names
  • parents
  • partition
  • rate
  • rollup
  • setUnit
  • smooth
  • sort
  • splitBy
  • timeshift
  • toUnit

Can be null.

unitstring

The unit of the metric.

Can be null.

warningsstring[]

A list of potential warnings that affect this ID. For example deprecated feature usage etc.

Can be null.

createdinteger

The timestamp of metric creation.

Built-in metrics and metric expressions have the value of null.

Can be null.

The MetricDimensionDefinition object

The dimension of a metric.

ElementTypeDescription
displayNamestring

The display name of the dimension.

namestring

The name of the dimension.

keystring

The key of the dimension.

It must be unique within the metric.

typestring

The type of the dimension.

The element can hold these values
  • ENTITY
  • NUMBER
  • OTHER
  • STRING
  • VOID
indexinteger

The unique 0-based index of the dimension.

Appending transformations such as :names or :parents may change the indexes of dimensions. null is used for the dimensions of a metric with flexible dimensions, which can be referenced with their dimension key, but do not have an intrinsic order that could be used for the index.

The MetricDimensionCardinality object

The dimension cardinalities of a metric.

ElementTypeDescription
relativenumber

The relative cardinality of the dimension expressed as percentage

estimateinteger

The cardinality estimate of the dimension.

keystring

The key of the dimension.

It must be unique within the metric.

The MetricDefaultAggregation object

The default aggregation of a metric.

ElementTypeDescription
typestring

The type of default aggregation.

The element can hold these values
  • auto
  • avg
  • count
  • max
  • median
  • min
  • percentile
  • sum
  • value

Can be null.

parameternumber

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

Applicable only to the percentile aggregation type.

Can be null.

The MetricValueType object

The value type for the metric.

ElementTypeDescription
typestring

The metric value type

The element can hold these values
  • error
  • score
  • unknown

Response body JSON model

json
{ "metricId": "builtin:host.cpu.user:splitBy(\"dt.entity.host\"):max:fold", "displayName": "CPU user", "description": "Percentage of user-space CPU time currently utilized, per host.", "unit": "Percent", "dduBillable": false, "created": 1597400123451, "lastWritten": 1597400717783, "entityType": [ "HOST" ], "aggregationTypes": [ "auto", "value" ], "transformations": [ "filter", "fold", "limit", "merge", "names", "parents", "timeshift", "rate", "sort", "last", "splitBy" ], "defaultAggregation": { "type": "value" }, "dimensionDefinitions": [ { "key": "dt.entity.host", "name": "Host", "displayName": "Host", "index": 0, "type": "ENTITY" } ], "tags": [], "metricValueType": { "type": "unknown" }, "dimensionCardinalities": [ { "key": "dt.entity.host", "estimate": 20, "relative": 0.2 } ], "latency": 1, "scalar": false }

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

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

Request URL

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

Response body

json
{ "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.

plaintext
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