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 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:

1. 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.iowait has only the dimension dt.entity.host, but builtin:host.disk.throughput.read has the dimensions dt.entity.host and dt.entity.disk.

   You need to get rid of the dt.entity.disk dimension (for example, by appending :merge(dt.entity.disk) to builtin:host.disk.throughput.read).

2. 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().

3. 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 neither errorCount nor totalCount. The result will be empty.

There are multiple reasons why a datapoint could be unavailable:

1. Make sure that you receive a response with the 202 HTTP status code for the ingest endpoint.
2. 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.
3. 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.
4. 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.