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 rowtext/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 | ManagedDynatrace for Government | 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 metrics.read
scope.
To learn how to obtain and use it, see Tokens and authentication.
Parameters
Parameter | Type | Description | In | Required |
---|---|---|---|---|
metricKey | string | The key of the required metric. You can set additional transformation operators, separated by a colon ( | path | required |
Response
Response codes
Code | Type | Description |
---|---|---|
200 | Metric | 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.
Element | Type | Description |
---|---|---|
dduBillable | boolean | If Metric expressions don't return this field. |
lastWritten | integer | The timestamp when the metric was last written. Has the value of |
impactRelevant | boolean | The metric is ( 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. |
minimumValue | number | The minimum allowed value of the metric. Metric expressions don't return this field. |
defaultAggregation | Metric | The default aggregation of a metric. |
dimensionDefinitions | Metric | 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. |
rootCauseRelevant | boolean | The metric is ( A root-cause relevant metric represents a strong indicator for a faulty component. Metric expressions don't return this field. |
maximumValue | number | The maximum allowed value of the metric. Metric expressions don't return this field. |
latency | integer | 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. |
resolutionInfSupported | boolean | If 'true', resolution=Inf can be applied to the metric query. |
unitDisplayFormat | string | 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. |
dimensionCardinalities | Metric | The cardinalities of MINT metric dimensions. |
entityType | string[] | List of admissible primary entity types for this metric. Can be used for the |
metricId | string | The fully qualified key of the metric. If a transformation has been used it is reflected in the metric key. |
metricSelector | string | The metric selector that is used when querying a func: metric. |
scalar | boolean | Indicates whether the metric expression resolves to a scalar ( |
aggregationTypes | string[] | The list of allowed aggregations for this metric. |
metricValueType | Metric | The value type for the metric. |
created | integer | The timestamp of metric creation. Built-in metrics and metric expressions have the value of |
displayName | string | The name of the metric in the user interface. |
description | string | A short description of the metric. |
transformations | string[] | Transform operators that could be appended to the current transformation list. |
unit | string | The unit of the metric. |
warnings | string[] | A list of potential warnings that affect this ID. For example deprecated feature usage etc. |
tags | string[] | The tags applied to the metric. Metric expressions don't return this field. |
The MetricDefaultAggregation
object
The default aggregation of a metric.
Element | Type | Description |
---|---|---|
type | string | The type of default aggregation. |
parameter | number | The percentile to be delivered. Valid values are between Applicable only to the |
The MetricDimensionDefinition
object
The dimension of a metric.
Element | Type | Description |
---|---|---|
displayName | string | The display name of the dimension. |
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. |
index | integer | The unique 0-based index of the dimension. Appending transformations such as :names or :parents may change the indexes of dimensions. |
The MetricDimensionCardinality
object
The dimension cardinalities of a metric.
Element | Type | Description |
---|---|---|
relative | number | The relative cardinality of the dimension expressed as percentage |
estimate | integer | The cardinality estimate of the dimension. |
key | string | The key of the dimension. It must be unique within the metric. |
The MetricValueType
object
The value type for the metric.
Element | Type | Description |
---|---|---|
type | string | The metric value type |
Response body JSON model
{
"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
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
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