<METRIC_NAME>:<VALUE>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>
Parameter | Required | Description |
---|
<METRIC_NAME> | Yes | A string that contains only ASCII alphanumerics, underscores, and periods. See the metric naming policy. |
<VALUE> | Yes | An integer or float. |
<TYPE> | Yes | c for COUNT, g for GAUGE, ms for TIMER, h for HISTOGRAM, s for SET, d for DISTRIBUTION. See Metric Types for more details. |
<SAMPLE_RATE> | No | A float between 0 and 1 , inclusive. Only works with COUNT, HISTOGRAM, DISTRIBUTION, and TIMER metrics. The default is 1 , which samples 100% of the time. |
<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2> | No | A comma separated list of strings. Use colons for key/value tags (env:prod ). For guidance on defining tags, see Getting Started with Tags. |
Here are some example datagrams:
page.views:1|c
: Increment the page.views
COUNT metric.fuel.level:0.5|g
: Record the fuel tank is half-empty.song.length:240|h|@0.5
: Sample the song.length
histogram as if it was sent half of the time.users.uniques:1234|s
: Track unique visitors to the site.users.online:1|c|#country:china
: Increment the active users COUNT metric and tag by country of origin.users.online:1|c|@0.5|#country:china
: Track active China users and use a sample rate.
DogStatsD protocol v1.1
Starting with the Agent >=v6.25.0
&& <v7.0.0
or >=v7.25.0
, value packing is possible. This
is supported for all metric types except SET
. Values are separated by a :
, for example:
<METRIC_NAME>:<VALUE1>:<VALUE2>:<VALUE3>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>
TYPE
, SAMPLE_RATE
, and TAGS
are shared between all values. This produces the same metrics than sending multiple
messages with one value in each. This is useful for HISTOGRAM, TIMING, and DISTRIBUTION metrics.
Example datagrams
page.views:1:2:32|d
: Sample the page.views
DISTRIBUTION metric three times with values 1
, 2
and 32
.song.length:240:234|h|@0.5
: Sample the song.length
histogram as if it was sent half of the time, twice. Each value has the sample rate of 0.5
applied to it.
DogStatsD protocol v1.2
Starting with the Agent >=v6.35.0
&& <v7.0.0
or >=v7.35.0
, a new container ID field is supported.
The Datadog Agent uses the container ID value to enrich DogStatsD metrics with additional container tags.
The container ID is prefixed by c:
, for example:
<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|c:<CONTAINER_ID>
Note: Set dogstatsd_origin_detection_client
to true
in your datadog.yaml
file or the environment variable DD_DOGSTATSD_ORIGIN_DETECTION_CLIENT=true
to instruct the Datadog Agent to extract the container ID field and attach the corresponding container tags.
Example datagrams
page.views:1|g|#env:dev|c:83c0a99c0a54c0c187f461c7980e9b57f3f6a8b0c918c8d93df19a9de6f3fe1d
: The Datadog Agent adds container tags like image_name
and image_tag
to the page.views
metric.
Read more about container tags in the Kubernetes and Docker tagging documentation.
DogStatsD protocol v1.3
Agents v6.40.0+
and v7.40.0+
support an optional Unix timestamp field.
When this field is provided, the Datadog Agent doesn’t do any processing with the metrics (no aggregation) except from enriching the metrics with tags. This can be useful if you already aggregate your metrics in your application, and you want to send them to Datadog without extra processing.
The Unix timestamp should be a valid positive number in the past. Only GAUGE and COUNT metrics are supported.
The value is a Unix timestamp (UTC) and must be prefixed by T
, for example:
<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|T<METRIC_TIMESTAMP>
Example datagram
page.views:15|c|#env:dev|T1656581400
: A COUNT indicating that 15 page views happened on the 30th of June, 2022 at 9:30am UTC
DogStatsD protocol v1.4
Starting with the Agent >=v7.51.0
, a new inode value is supported for the container ID field.
The container ID field can now contain two values to enrich DogStatsD metrics with additional container tags:
- The container ID if available.
- The cgroup node inode if the container ID is unavailable.
The container ID field is still prefixed by c:
, with the value being either:
c:ci-<CONTAINER_ID>
c:in-<CGROUP_INODE>
For backward compatibility, we still support the following format, although it is considered deprecated:
DogStatsD protocol v1.5
Starting with the Agent >=v7.57.0
, a new External Data field is supported.
The Datadog Agent uses the External Data value to enrich DogStatsD metrics with additional container tags when the container ID is unavailable.
The container ID is prefixed by e:
, for example:
<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|e:<EXTERNAL_DATA>
This data is supplied by the Datadog Agent Admission Controller and will contain:
- A boolean representing if the container is an init container or not.
- The container name.
- The pod UID.
The format is as follow:
it-INIT_CONTAINER,cn-CONTAINER_NAME,pu-POD_UID
It would look like:
it-false,cn-nginx-webserver,pu-75a2b6d5-3949-4afb-ad0d-92ff0674e759
DogStatsD protocol v1.6
Starting with the Agent >=v7.64.0
, a new Cardinality field is supported.
The Datadog Agent uses the cardinality value to enrich DogStatsD metrics with additional container tags corresponding to their cardinality.
The cardinality field is prefixed by card:
, for example:
<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|card:<CARDINALITY>
Cardinality will impact tags enrichment for both:
The available values for cardinality are: