Metrics API - GET metric data points
Gets data points of the specified metrics.
You can receive either one aggregated data point per tuple (unique combinations of metric—dimension—dimension value) or a list of data points per tuple. See the description of the resolution parameter of the request for more information.
The following limits apply:
- The number of data points is limited to 20,000,000.
- The number of tuples is limited to 100,000.
If exceeded, only the first 100,000 tuples (a:sort
transformation doesn't affect these) are processed and the rest are ignored. - The number of data points per tuple is limited to 10,080.
- The number of monitored entities is limited to 5,000 per each entitySelector in the query.
These limits apply to the datapoints that the query reads in the database. The amount of datapoints in the final result might be different. For example, if the :fold
transformation is used, the query reads multiple data points but returns just one aggregated data point per tuple.
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 | SaaS | https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/query |
Environment ActiveGateCluster ActiveGate | https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/metrics/query |
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 |
---|---|---|---|---|
metricSelector | 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, If the metric key contains any symbols you must quote (
For example, to query the metric with the key of ext:selfmonitoring.jmx.Agents: Type "APACHE" you must specify this selector:
You can set additional transformation operators, separated by a colon ( | query | optional |
resolution | string | The desired resolution of data points. You can use one of the following options:
Valid units for the timespan are:
If not set, the default is 120 data points. For example:
| query | optional |
from | string | The start of the requested timeframe. You can use one of the following formats:
If not set, the relative timeframe of two hours is used ( | query | optional |
to | string | The end of the requested timeframe. You can use one of the following formats:
If not set, the current timestamp is used. | query | optional |
entitySelector | string | Specifies the entity scope of the query. Only data points delivered by matched entities are included in response. You must set one of these criteria:
You can add one or more of the following criteria. Values are case-sensitive and the
For more information, see Entity selector in Dynatrace Documentation. To set several criteria, separate them with a comma ( The maximum string length is 2,000 characters. Use the To set a universal scope matching all entities, omit this parameter. | query | optional |
mzSelector | string | The management zone scope of the query. Only metrics data relating to the specified management zones are included to the response. You can set one or more of the following criteria. Values are case-sensitive and the
| query | optional |
Response
Response codes
Code | Type | Description |
---|---|---|
200 | Metric | Success |
400 | - | Syntax or validation error. From and to parameters, entitySelector or resolution are incorrect individually or in their combined meaning. |
404 | - | A metric has not been found. |
406 | - | Not acceptable. The requested media type is not supported. Check the Accept header of your request. |
4XX | Error | Client side error. |
5XX | Error | Server side error. |
Response body objects
The MetricData
object
A list of metrics and their data points.
Element | Type | Description |
---|---|---|
nextPageKey | string | Deprecated. This field is returned for compatibility reasons. It always has the value of |
resolution | string | The timeslot resolution in the result. |
result | Metric | A list of metrics and their data points. |
totalCount | integer | The total number of primary entities in the result. Has the |
warnings | string[] | A list of warnings |
The MetricSeriesCollection
object
Data points of a metric.
Element | Type | Description |
---|---|---|
appliedOptionalFilters | Applied | A list of filtered metric keys along with filters that have been applied to these keys, from the |
data | Metric | Data points of the metric. |
dataPointCountRatio | number | The ratio of queried data points divided by the maximum number of data points per metric that are allowed in a single query. |
dimensionCountRatio | number | The ratio of queried dimension tuples divided by the maximum number of dimension tuples allowed in a single query. |
dql | Metric | Metric query translation to DQL. |
metricId | string | The key of the metric. If any transformation is applied, it is included here. |
warnings | string[] | A list of potential warnings that affect this ID. For example deprecated feature usage etc. |
The AppliedFilter
object
Optional filters that took effect.
Element | Type | Description |
---|---|---|
appliedTo | string[] | The keys of all metrics that this filter has been applied to. Can contain multiple metrics for complex expressions and always at least one key. |
filter | Filter | A dimensional or series filter on a metric. |
The Filter
object
A dimensional or series filter on a metric.
Element | Type | Description |
---|---|---|
operands | Filter[] | If the type is |
referenceInvocation | Invocation | Invocation of a function, e.g. the |
referenceString | string | For filters that match a dimension against a valkue, such as |
referenceValue | number | For the operands of |
rollup | Rollup | A way of viewing a series as a single value for the purpose of sorting or series-based filters. |
targetDimension | string | If the type applies to a dimension, then holds the target dimension. |
targetDimensions | string[] | If the type applies to n dimensions, then holds the target dimensions. Currently only used for the |
type | string | Type of this filter, determines which other fields are present.Can be any of:
|
The Invocation
object
Invocation of a function, e.g. the entitySelector
function.
Element | Type | Description |
---|---|---|
args | string[] | Arguments to pass to the function, e.g. entity selector source code. |
function | string | Function that is invoked, e.g. |
The Rollup
object
A way of viewing a series as a single value for the purpose of sorting or series-based filters.
Element | Type | Description |
---|---|---|
parameter | number | - |
type | string | -
|
The MetricSeries
object
Data points per dimension of a metric.
The data is represented by two arrays of the same length: timestamps and values. Entries of the same index from both arrays form a timestamped data point.
Element | Type | Description |
---|---|---|
dimensionMap | object | - |
dimensions | string[] | Deprecated, refer to The ordered list of dimensions to which the data point list belongs. Each metric can have a certain number of dimensions. Dimensions exceeding this number are aggregated into one, which is shown as |
timestamps | integer[] | A list of timestamps of data points. The value of data point for each time from this array is located in values array at the same index. |
values | number[] | A list of values of data points. The timestamp of data point for each value from this array is located in timestamps array at the same index. |
The MetricQueryDQLTranslation
object
Metric query translation to DQL.
Element | Type | Description |
---|---|---|
message | string | Error message - only present if the status is |
query | string | The DQL query corresponding to the metric query |
status | string | The status of the DQL translation, either
|
Response body JSON model
{"nextPageKey": "null","resolution": "1h","result": [{"data": [{"dimensionMap": {"dt.entity.disk": "DISK-F1266E1D0AAC2C3F","dt.entity.host": "HOST-F1266E1D0AAC2C3C"},"dimensions": ["HOST-F1266E1D0AAC2C3C","DISK-F1266E1D0AAC2C3F"],"timestamps": [3151435100000,3151438700000,3151442300000],"values": [11.1,22.2,33.3]},{"dimensions": ["HOST-F1266E1D0AAC2C3C","DISK-F1266E1D0AAC2C3D"],"timestamps": [3151435100000,3151438700000,3151442300000],"values": [111.1,222.2,333.3]}],"dataPointCountRatio": "0.1211","dimensionCountRatio": "0.0322","metricId": "builtin:host.disk.avail"},{"data": [],"metricId": "builtin:host.cpu.idle:filter(eq(\"dt.entityhost\",HOST-123))","warnings": ["The dimension key `dt.entityhost` has been referenced, but the metric has no such key."]}],"totalCount": 3,"warnings": ["The dimension key `dt.entityhost` has been referenced, but the metric has no such key."]}
Timeframe note
Dynatrace stores data in time slots. The MetricValue object shows the ending timestamp of the slot. If the time, set in the from or to parameters of your query, falls within the data time slot, this time slot is included in the response.
If the timestamp of the last data slot lays outside of the specified timeframe, the last data point of the response has a later timestamp than the specified in to query parameter.
Dynatrace does not predict future data. The timestamp of the last data point may lay in the future, due to data slots principle, described above. In this case, this data slot has incomplete data.
Examples
In these examples, the requests query the data points of the builtin:host.cpu.usage and builtin:host.cpu.idle metrics.
The timeframe is set to last 5 minutes. To achieve that, the from query parameter is set to now-5m
.
Only data from these two hosts (HOST-0990886B7D39FE29 and HOST-0956C3557E9109C1) is included in the response. To achieve this, the entitySelector query parameter is set to type("dt.entity.host"),entityId("HOST-0990886B7D39FE29")
.
Because host is a dimension of the queried metrics, you can achieve the same filtering by applying the :filter
transformation to the metrics themselves by setting the metricSelector query parameter to builtin:host.cpu.(usage,idle):filter(or(eq("dt.entity.host","HOST-0990886B7D39FE29"),eq("dt.entity.host","HOST-0956C3557E9109C1")))
and omitting entitySelector as redundant.
The difference between the queries is the representation of data—the first shows the list of data points, while the second shows just one aggregated data point for each series (the :fold
transformation is applied at the end).
The API token is passed in the Authorization header.
The response is in application/json
format.