Metric ingestion protocol
This page describes the protocol for metric ingestion in Dynatrace.
The general syntax of metric ingestion is the following:
Metric key required
The key of the metric you're submitting. It consists of sections, separated by dots, for example
Allowed characters are lowercase and uppercase letters, numbers, hyphens (
-), and underscores (
_). The following restrictions apply:
- Non-latin letters (like
ö) are not allowed.
- Metric keys cannot start with a number or a hyphen (
- Sections cannot start with a hyphen (
- The length of the key must be in range from 3 to 250 characters.
The metric key ends either at the first comma (if you're specifying dimensions) or at the first whitespace (if you omit dimensions).
Your provided key may be suffixed automatically depending on the payload. For details, see Payload.
If you want to omit dimensions, provide the payload right after the metric key, separated by a whitespace.
Dimensions are specified as
key="value" pairs. You can specify up to 50 dimensions, separated by commas (
Allowed characters for the key are lowercase letters, numbers, hyphens (
-), periods (
.), and underscores (
_). Special letters (like
ö) are not allowed. The key can be in the
Pass the dimension value as a quoted string. If you want to pass quotes (
") and/or backslashes (
\) in a dimension value, make sure you escape them with a backslash (
\). For example:
Currently we support only one dimension value per dimension key. If the same dimension key is specified multiple times in a single payload (for example,
ipaddress="192.168.100.1",ipaddress="10.0.0.1") the payload is valid, but only one value is accepted.
Dynatrace reserved dimensions
dt.entity.<entity_type> key is a Dynatrace reserved dimension key that relates the metric to the monitored entity provided as dimension value (for example, the
dt.entity.host=HOST-06F288EE2A930951 dimension maps the data points to the host with the ID of HOST-06F288EE2A930951).
The general format of the payload is the following:
You can specify a payload in two formats: gauge (
gauge) or count value (
count). Specify the format before you specify data points and separate it from data points with a comma (for example
A metric key can only refer to one payload type. Thus, your provided metric key is automatically suffixed with
.count for the payload type
count unless the key already ends with
.count. Vice versa, if the key of a metric with type gauge ends with
.count, it is suffixed with
For the gauge format, you can specify the following statistic summaries:
count—the number of measurements included in the data point.
You can omit the format if you're using a single value gauge payload. In that case, the provided value is used for all summaries and the count is set to
For example, a payload of
Usage of the count format will automatically create a new metric with the
your-metric-key.count key. To specify the count value, you must provide the delta field:
Data points of the
count type are deltas between the previous and current data points. For example, if the initial data point has the value of
500 and the second data point has the value of
1,000, the actual stored value at the timestamp of the second data point is
Data point required
A data point might include one or, in the case of the gauge format, several measures. For several measures, provide them with statistic summaries. You must specify all the summaries.
A data point of the
count type is the delta between the previous and current data points.
The format of the timestamp is UTC milliseconds. Allowed range is between 1 hour into the past and 10 minutes into the future from now. If no timestamp is provided, the current timestamp of the server is used.
You can provide custom metric metadata via the ingestion protocol. The ingestion protocol supports only creation of metadata. If metadata for the same metric is specified several times in the payload, only the first occurrence is used. To view or update metadata, use either Metrics browser or the Settings API (to learn how to compose an API payload, see Set metric metadata).
#metric.key <payload-format> dt.meta.<property>="<value>"
count in place of
<payload-format>. Usage of the count format will automatically create a new metric with the
The following properties are available. To specify several properties, separate them with a comma (
|dt.meta.displayName||string||The name of the metric in the user interface.|
|dt.meta.description||string||A short description of the metric.|
The unit of the metric.
Find the possible values in the description of the unit field for built-in metrics.
The general syntax of metric ingestion is the following:
metric.key,dimensions payload #metric.key <payload-format> dt.meta.<property1>="<value>", dt.meta.<property2>="<value>"
Here's an example of a metric using multiple dimensions,
businessapp that describe the reported datapoints.
Here's the same example with the timestamp of the data point.
mymetric,team=teamA,businessapp=hr 1000 1609459200000
Gauge is the default data, so you can keep the data type optional in case you want to send gauge values:
cpu.temperature,hostname=hostA,cpu=1 55 cpu.temperature,hostname=hostA,cpu=2 45
Here's an example with the
gauge data type used nonetheless.
You can also provide consolidated information about multiple datapoints recorded on the client side before sending it to Dynatrace. In the example below, 2 datapoints are summarized and the minimum, maximum, sum value and number of datapoints are sent in a single line.
You can also relate measurements to existing host entities by making use of the
dt.entity.host reserved dimension key.
Note: You don't need to specify the
dt.entity.host dimension when using local ingestion methods via OneAgent, that is dynatrace_ingest and local API, because for this ingestion methods, the host context is added automatically.
For a count type of metric, the delta is calculated and provided by the client that sends the metric to Dynatrace, which in the case below represents new users reported by region.
new_user_count,region=EAST count,delta=50 new_user_count,region=WEST count,delta=150
Here's an example of providing metadata for a
cpu.temperature gauge,45 #cpu.temperature gauge dt.meta.unit=count,dt.meta.description="The temperature of the CPU",dt.meta.displayname="CPU temperature"
See POST ingest data points for an example API call.