Metric ingestion protocol

This page describes the protocol for metric ingestion in Dynatrace.

Syntax

The general syntax of metric ingestion is the following:

httpcopydownload
metric.key,dimensions payload

Metric key required

The key of the metric you're submitting. It consists of sections, separated by dots, for example first.second.third.

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.

Dimension optional

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 key.key-section format.

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:

httpcopydownload
workHours,team="devops\\bugfixing",project="\"product\"_improvement" 1000

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

The 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).

Payload required

The general format of the payload is the following:

httpcopydownload
format,dataPoint timestamp

Format optional

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 gauge,80.6).

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 .gauge.

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.

Timestamp optional

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.

Metadata optional

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

httpcopydownload
#metric.key <payload-format> dt.meta.<property>="<value>"

Set either gauge or count in place of <payload-format>. Usage of the count format will automatically create a new metric with the m§etric-key.count key.

The following properties are available. To specify several properties, separate them with a comma (,).

Examples

The general syntax of metric ingestion is the following:

httpcopydownload
metric.key,dimensions payload
#metric.key <payload-format> dt.meta.<property1>="<value>", dt.meta.<property2>="<value>"

Dimensions

Here's an example of a metric using multiple dimensions, team and businessapp that describe the reported datapoints.

httpcopydownload
mymetric,team=teamA,businessapp=hr 1000

Here's the same example with the timestamp of the data point.

httpcopydownload
mymetric,team=teamA,businessapp=hr 1000 1609459200000

GAUGE metric

Gauge is the default data, so you can keep the data type optional in case you want to send gauge values:

httpcopydownload
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.

httpcopydownload
cpu.temperature,hostname=hostA,cpu=1 gauge,45

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.

httpcopydownload
cpu.temperature,hostname=hostA,cpu=1 gauge,min=17.1,max=17.3,sum=34.4,count=2

You can also relate measurements to existing host entities by making use of the dt.entity.host reserved dimension key.

httpcopydownload
cpu.temperature,dt.entity.host=HOST-4587AE40F95AD90D,cpu=1 gauge,min=17.1,max=17.3,sum=34.4,count=2

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.

COUNT metric

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.

httpcopydownload
new_user_count,region=EAST count,delta=50
new_user_count,region=WEST count,delta=150

Create metadata

Here's an example of providing metadata for a cpu.temperature metric.

httpcopydownload
cpu.temperature gauge,45
#cpu.temperature gauge dt.meta.unit=count,dt.meta.description="The temperature of the CPU",dt.meta.displayname="CPU temperature"

API call

See POST ingest data points for an example API call.