Metrics API FAQ
Metric query
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 sum
or count
.
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 builtin:host.availability:splitBy():fold
instead).
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 null
.
By default, the query response only contains the IDs of the monitored entities (for example, HOST-E1784F5E3F9987CD
).
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, dt.entity.host.name
).
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 errorMetric expression contains non-matching dimension-keys.
becausebuiltin:host.cpu.iowait
has only the dimensiondt.entity.host
, butbuiltin:host.disk.throughput.read
has the dimensionsdt.entity.host
anddt.entity.disk
.You need to get rid of the
dt.entity.disk
dimension (for example, by appending:merge(dt.entity.disk)
tobuiltin:host.disk.throughput.read
). -
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 / totalCount
and 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 neithererrorCount
nortotalCount
. The result will be empty.
Metric ingest
There are multiple reasons why a datapoint could be unavailable:
- Make sure that you receive a response with the
202
HTTP 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:
count
metrics are automatically suffixed with.count
unless their metric key already ends with.count
or_count
gauge
metrics are automatically suffixed with.gauge
if their key ends with.count
or_count
.
You can write the metadata of a metric via the ingestion protocol only once. To update the metric metadata, you need to use the metric browser.
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.