Metrics API FAQ
In Dynatrace, metric datapoints are stored in time slots of different resolutions. The finest granularity of a time slot is one minute. The timestamps returned by the metrics query endpoint are the end times of these time slots.
For example, if the current time is 09:24 a.m. and you query the last 6 hours at a 1-hour resolution, the timestamp of the last datapoint will be today at 10:00 a.m. For details, see Timeframe note.
The datapoints returned by the query endpoint are time-aggregated. Depending on the query timeframe, the resolution of the datapoints may be minutes, hours, days, or even years. If you query a larger timeframe, the resolution of your data is likely to be coarser, causing greater values for aggregations such as
If you want to have comparable results for different resolutions, use the rate transformation. For example,
:rate(1m) provides you with the value per minute.
If you query, for example,
builtin:host.availability:splitBy():avg:fold, the returned value may be higher than 100% even though the metric has
Percent as its unit.
The root cause of this problem is that when you apply an aggregation transformation (by calling
:avg in the example above), the semantics of the metric are lost and not available for transformations coming later in the transformation chain. That is, when the fold transformation is called, the information that the values should be averaged is not available anymore and, instead, the aggregation
sum is applied.
To prevent this issue, do not perform an aggregation prior a fold transformation (query
If a top x is applied to a dimension of a metric, only x dimension values are retained. All other dimension values are booked into the
remainder dimension, which has the value
By default, the query response only contains the IDs of the monitored entities (for example,
If you want to have the entity name in the response as well, you need to use the names transformation. The pretty name is then available in the
dimensionMap under the dimension key
dt.entity.<entityType>.name for example,
There are multiple reasons why a metric expression could yield an empty result:
The dimension keys of the metrics used in the expression do not match.
If you have metrics with different dimension keys, you need to align the dimensions of the metrics to make a calculation possible. You can use either the split by or merge transformation for this purpose.
For instance, if you query
builtin:host.cpu.iowait / builtin:host.disk.throughput.read, you will get the error
Metric expression contains non-matching dimension-keys.because
builtin:host.cpu.iowaithas only the dimension
builtin:host.disk.throughput.readhas the dimensions
You need to get rid of the
dt.entity.diskdimension (for example, by appending
The dimension values do not match.
For example, the expression
builtin:host.cpu.iowait:filter(eq(dt.entity.host,HOST-F8D60EB24F4B9971)) / builtin:host.cpu.iowait:filter(eq(dt.entity.host,HOST-22025B9C2BBBE35A))will yield an empty result because different dimension values cannot be joined.
The solution in this case is to drop the dimensions completely using the split by transformation:
builtin:host.cpu.iowait:filter(eq(dt.entity.host,HOST-F8D60EB24F4B9971)):splitBy() / builtin:host.cpu.iowait:filter(eq(dt.entity.host,HOST-22025B9C2BBBE35A)):splitBy().
There is no data for a metric.
For example, if you calculated the error ratio using the expression
errorCount / totalCountand there were no errors booked for the queried timeframe, the result would be empty. You can use the default transformation to manually set the error count to 0 and get a result (
errorCount:default(0) / totalCount).
However, if both metrics of an expression have no data for the queried timeframe, you cannot fill up the time slots using the default transformation. That is,
(errorCount / totalCount):default(0)does not work if there is data for neither
totalCount. The result will be empty.
There are multiple reasons why a datapoint could be unavailable:
- Make sure that you receive a response with the
202HTTP status code for the ingest endpoint.
- It may take a couple of minutes until an ingested datapoint becomes available via the Metrics REST API and in the Data Explorer. The solution is to wait.
- Check whether the datapoint was rejected at a later stage by opening the dashboard Metric & Dimension Usage + Rejections Dynatrace version 1.239+. It may happen that a datapoint is accepted by the ingestion endpoint, but later rejected because an invariant was broken.
- Check the applied request filters. The datapoint may be filtered out by a management zone or a timeframe filter.
Metrics with different payload types cannot share the same key. Therefore:
countmetrics are automatically suffixed with
.countunless their metric key already ends with
gaugemetrics are automatically suffixed with
.gaugeif their key ends with
If you ingest a dimension with an empty value, the whole dimension tuple is dropped at ingestion time. For instance, if you ingest
myMetric,dimEmpty="" 1, the dimension
dimEmpty is removed.