New announcements for Serverless, Network, RUM, and more from Dash! New announcements from Dash!

Datagram Format and Shell Usage

This section specifies the raw datagram format for metrics, events, and service checks that DogStatsD accepts. 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.

<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. See the metric type documentation.
<SAMPLE_RATE>NoA float between 0 and 1, inclusive. Only works with COUNT, HISTOGRAM, 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). See the tagging documentation for guidance on defining tags.

Here are some example datagrams:

  • page.views:1|c : Increment the page.views counter.
  • fuel.level:0.5|g: Record the fuel tank is half-empty.
  • song.length:240|h|@0.5: Sample the song.length histogram half of the time.
  • users.uniques:1234|s: Track unique visitors to the site.
  • users.online:1|c|#country:china: Increment the active users counter and tag by country of origin.
  • users.online:1|c|@0.5|#country:china: Track active China users and use a sample rate.

_e{<TITLE>.length,<TEXT>.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.
d:<TIMESTAMP>NoAdd a timestamp to the event. The default is the current Unix epoch timestamp.
h:<HOSTNAME>NoAdd a hostname to the event. No default.
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. Refer to the main DogStatsD documentation to learn how to configure 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):

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

Note: The Agent’s embedded Python interpreter can be used. On Windows, it is located at C:\Program Files\Datadog\Datadog Agent\embedded\python.exe for Agent versions <= 6.11 and in C:\Program Files\Datadog\Datadog Agent\embedded2\python.exe for Agent versions >= 6.12.

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, refer to the DogStatsD on Kubernetes documentation, in conjunction with the instructions for configuring APM on Kubernetes using DaemonSets or Helm, depending on your installation. The Docker APM documentation may also be helpful.

Further Reading