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 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 |
|
Authentication
To execute this request, you need the Read metrics (metrics.read
) permission assigned to your API token. To learn how to obtain and use it, see Tokens and authentication.
Parameters
Parameter | Type | Description | In | Required |
---|---|---|---|---|
metricId | string |
The key of the required metric. You can set additional transformation operators, separated by a colon ( The length of the string is limited to 2,000 characters. |
path | required |
Response
Response codes
Code | Description |
---|---|
200 | Success |
404 | Not found. The requested resource is not found or the query is incorrect. |
406 | Not acceptable. The requested media type is not supported. Check the Accept header of your request. |
Response body
The MetricDescriptor object
The descriptor of a metric.
Element | Type | Description |
---|---|---|
defaultAggregation |
Metric |
|
dimensionDefinitions |
Metric |
The fine metric division (for example, process group and process ID for some process-related metric). |
rootCauseRelevant | boolean | The metric is ( |
minimumValue | number | The minimum value of the metric. |
lastWritten | integer | The timestamp when the metric was last written. Has the value of |
impactRelevant | boolean | The metric is ( |
dduBillable | boolean | If |
maximumValue | number | The maximum value of the metric. |
tags | string[] | The tags applied to the metric |
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. |
aggregationTypes | string[] | The list of allowed aggregations for this metric. |
metricValueType | MetricValueType | |
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. Must be enabled with the "fields" parameter on |
unit | string | The unit of the metric. |
warnings | string[] | A list of potential warnings that affect this ID. For example deprecated feature usage etc. |
created | integer | The timestamp of metric creation. Built-in metrics have the value of |
The MetricValueType object
The value type for the metric.
Element | Type | Description |
---|---|---|
type | string | The metric value type |
The MetricDimensionDefinition object
The dimension of a metric.
Element | Type | Description |
---|---|---|
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. |
displayName | string | The display name 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 MetricDefaultAggregation object
The default aggregation of a metric.
Element | Type | Description |
---|---|---|
parameter | number | The percentile to be delivered. Valid values are between Applicable only to the |
type | string | The type of default aggregation. |
{
"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.\n",
"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"
}
}
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