Metrics ingestion protocol

This page describes the protocol for metric ingestion via

Syntax

The general syntax of metric ingestion is the following:

metric.key,dimensions payload

Metric key required

The key of the metric you're submitting. You can specify it in any format you want, as long as you start it with a lowercase letter. Allowed characters are lowercase and uppercase letters, numbers, hyphens (-), and underscores (_). Special letters (like ö) are not allowed.

The metric key ends either at the first comma (if you're specifying dimensions) or at the first whitespace (if you omit dimensions).

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 (-), 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:

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

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:

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

For the gauge format, you can specify the following statistic summaries:

  • min
  • max
  • sum
  • 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 1.

For example, a payload of 80.6 equals gauge,min=80.6,max=80.6,sum=80.6,count=1.

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.

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.

Examples

Dimensions

The general syntax of metric ingestion is the following:

metric.key,dimensions payload

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

mymetric,team=teamA,businessapp=hr 1000

GAUGE metric

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

cpu.temperature,dt.entity.host=HOST-06F288EE2A930951,cpu=1 55
cpu.temperature,dt.entity.host=HOST-06F288EE2A930951,cpu=2 45

Here's an example with the gauge data type used nonetheless.

cpu.temperature,dt.entity.host=HOST-8EBF2551F61F9112,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.

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

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

API call

See POST ingest data points for an example API call.