Datagram Format and Shell Usage

This section specifies the raw datagram format for metrics, events, and service checks that DogStatsD accepts. The raw datagrams are encoded in UTF-8. This isn’t required reading if you’re using any of the DogStatsD client libraries; however, if you want to write your own library, or use the shell to send metrics, then read on.

The DogStatsD protocol

<METRIC_NAME>:<VALUE>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

ParameterRequiredDescription
<METRIC_NAME>YesA string that contains only ASCII alphanumerics, underscores, and periods. See the metric naming policy.
<VALUE>YesAn integer or float.
<TYPE>Yesc 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>NoA 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>NoA 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

_e{<TITLE_UTF8_LENGTH>,<TEXT_UTF8_LENGTH>}:<TITLE>|<TEXT>|d:<TIMESTAMP>|h:<HOSTNAME>|p:<PRIORITY>|t:<ALERT_TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

ParameterRequiredDescription
_eYesThe datagram must begin with _e.
<TITLE>YesThe event title.
<TEXT>YesThe event text. Insert line breaks with: \\n.
<TITLE_UTF8_LENGTH>YesThe length (in bytes) of the UTF-8-encoded <TITLE>
<TEXT_UTF8_LENGTH>YesThe length (in bytes) of the UTF-8-encoded <TEXT>
d:<TIMESTAMP>NoAdd a timestamp to the event. The default is the current Unix epoch timestamp.
h:<HOSTNAME>NoAdd a hostname to the event. Defaults to the Datadog Agent instance.
k:<AGGREGATION_KEY>NoAdd an aggregation key to group the event with others that have the same key. No default.
p:<PRIORITY>NoSet to normal or low. Default normal.
s:<SOURCE_TYPE_NAME>NoAdd a source type to the event. No default.
t:<ALERT_TYPE>NoSet to error, warning, info, or success. Default info.
#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>NoThe colon in tags is part of the tag list string and has no parsing purpose like for the other parameters. No default.

Here are some example datagrams:

## Send an exception
_e{21,36}:An exception occurred|Cannot parse CSV file from 10.0.0.17|t:warning|#err_type:bad_file

## Send an event with a newline in the text
_e{21,42}:An exception occurred|Cannot parse JSON request:\\n{"foo: "bar"}|p:low|#err_type:bad_request

_sc|<NAME>|<STATUS>|d:<TIMESTAMP>|h:<HOSTNAME>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|m:<SERVICE_CHECK_MESSAGE>

ParameterRequiredDescription
_scYesThe datagram must begin with _sc.
<NAME>YesThe service check name.
<STATUS>YesAn integer corresponding to the check status (OK = 0, WARNING = 1, CRITICAL = 2, UNKNOWN = 3).
d:<TIMESTAMP>NoAdd a timestamp to the check. The default is the current Unix epoch timestamp.
h:<HOSTNAME>NoAdd a hostname to the event (no default).
#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>NoSet the tags of the event. A list of strings separated by comma (no default).
m:<SERVICE_CHECK_MESSAGE>NoA message describing the current state of the service check. This field must be positioned last among the metadata fields (no default).

Here’s an example datagram:

# Send a CRITICAL status for a remote connection
_sc|Redis connection|2|#env:dev|m:Redis connection timed out after 10s

Send metrics using DogStatsD and the shell

For Linux and other Unix-like OS, use Bash. For Windows, use PowerShell and PowerShell-statsd (a simple PowerShell function that takes care of the network bits).

DogStatsD creates a message that contains information about your metric, event, or service check and sends it to a locally installed Agent as a collector. The destination IP address is 127.0.0.1 and the collector port over UDP is 8125. See DogStatsD for details on configuring the Agent.

The format for sending metrics is:

<METRIC_NAME>:<VALUE>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

The examples below send data points for a gauge metric called custom_metric with the shell tag.

On Linux:

echo -n "custom_metric:60|g|#shell" >/dev/udp/localhost/8125
echo -n "custom_metric:60|g|#shell" | nc -4u -w0 127.0.0.1 8125
echo -n "custom.metric.name:1|c"|nc -4u -w1 localhost 8125

On Windows:

PS C:\> .\send-statsd.ps1 "custom_metric:123|g|#shell"

On any platform with Python (on Windows, the Agent’s embedded Python interpreter can be used, which is located at %ProgramFiles%\Datadog\Datadog Agent\embedded\python.exe for Agent versions <= 6.11 and in %ProgramFiles%\Datadog\Datadog Agent\embedded<PYTHON_MAJOR_VERSION>\python.exe for Agent versions >= 6.12):

Python 2

import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) # UDP
sock.sendto("custom_metric:60|g|#shell", ("localhost", 8125))

Python 3

import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) # UDP
sock.sendto("custom_metric:60|g|#shell", ("localhost", 8125))

The format for sending events is:

_e{<TITLE>.length,<TEXT>.length}:<TITLE>|<TEXT>|d:<DATE_EVENT>|h:<HOSTNAME>|p:<PRIORITY>|t:<ALERT_TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>.

The examples below calculate the size of the event’s title and body.

On Linux:

$ title="Event from the shell"

$ text="This was sent from Bash!"

$ echo "_e{${#title},${#text}}:$title|$text|#shell,bash"  >/dev/udp/localhost/8125

On Windows:

PS C:> $title = "Event from the shell"
PS C:> $text = "This was sent from PowerShell!"
PS C:> .\send-statsd.ps1 "_e{$($title.length),$($text.Length)}:$title|$text|#shell,PowerShell"

The format for sending service checks is:

_sc|<NAME>|<STATUS>|d:<TIMESTAMP>|h:<HOSTNAME>|#<TAG_KEY_1>:<TAG_VALUE_1>|m:<SERVICE_CHECK_MESSAGE>

On Linux:

echo -n "_sc|Redis connection|2|#env:dev|m:Redis connection timed out after 10s" >/dev/udp/localhost/8125

On Windows:

PS C:\> .\send-statsd.ps1 "_sc|Redis connection|2|#env:dev|m:Redis connection timed out after 10s"

To send metrics, events, or service checks on containerized environments, see DogStatsD on Kubernetes, in conjunction with configuring APM on Kubernetes, depending on your installation. The Docker APM documentation may also be helpful.

Further Reading