Datadog Synthetics is now available!

Datagram Format and Shell Usage

This section specifies the raw datagram format for each data type 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 or events, then read on.

Datagram Format

Metrics

metric.name:value|type|@sample_rate|#tag1:value,tag2

Parameter Required Description
metric.name Yes a string with no colons, bars, or @ characters. See the metric naming policy.
value Yes an integer or float.
type Yes c for counter, g for gauge, ms for timer, h for histogram, s for set.
sample rate No a float between 0 and 1, inclusive. Only works with counter, histogram, and timer metrics. Default is 1 (i.e. sample 100% of the time).
tags No a comma separated list of tags. Use colons for key/value tags, i.e. env:prod. The key device is reserved; Datadog drops a user-added tag like device:foobar.

Here are some example datagrams:

# Increment the page.views counter
page.views:1|c

# Record the fuel tank is half-empty
fuel.level:0.5|g

# Sample the song length histogram half of the time
song.length:240|h|@0.5

# Track a unique visitor to the site
users.uniques:1234|s

# Increment the active users counter, tag by country of origin
users.online:1|c|#country:china

# Track active China users and use a sample rate
users.online:1|c|@0.5|#country:china

Events

_e{title.length,text.length}:title|text|d:timestamp|h:hostname|p:priority|t:alert_type|#tag1,tag2

Parameter Required Description
_e Yes The datagram must begin with _e
title Yes Event title.
text Yes Event text. Insert line breaks with an escaped slash (\\n)
d:timestamp No Add a timestamp to the event. Default is the current Unix epoch timestamp.
h:hostname No Add a hostname to the event. No default.
k:aggregation_key No Add an aggregation key to group the event with others that have the same key. No default.
p:priority No Set to ‘normal’ or ‘low’. Default ‘normal’.
s:source_type_name No Add a source type to the event. No default.
t:alert_type No Set to ‘error’, ‘warning’, ‘info’ or ‘success’. Default ‘info’.
#tag1:value1,tag2,tag3:value3... No The 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

Service Checks

_sc|name|status|d:timestamp|h:hostname|#tag1:value1,tag2,tag3:value3,...|m:service_check_message

Parameter Required Description
_sc Yes the datagram must begin with _sc
name Yes Service check name.
status Yes Integer corresponding to the check status (OK = 0, WARNING = 1, CRITICAL = 2, UNKNOWN = 3).
d:timestamp No Add a timestamp to the check. Default is the current Unix epoch timestamp.
h:hostname No Add a hostname to the event. No default.
#tag1:value1,tag2,tag3:value3,... No The colon in tags is part of the tag list string and has no parsing purpose like for the other parameters. No default.
m:service_check_message No Add a 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|#redis_instance:10.0.0.16:6379|m:Redis connection timed out after 10s

Send metrics and events using DogStatsD and the shell

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

The idea behind DogStatsD is simple: create a message that contains information about your metric/event, and send it to a collector over UDP on port 8125. Read more about the message format.

Sending metrics

The format for sending metrics is metric.name:value|type|@sample_rate|#tag1:value,tag2, so let’s go ahead and send datapoints for a gauge metric called custom_metric with the shell tag. Using a locally installed Agent as a collector, the destination IP address is 127.0.0.1.

Linux options:

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

Windows options:

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

On any platform with Python (on Windows, the Agent’s embedded Python interpreter can be used, which is located at C:\Program Files\Datadog\Datadog Agent\embedded\python.exe):

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

Sending events

The format for sending events is:

_e{title.length,text.length}:title|text|d:date_happened|h:hostname|p:priority|t:alert_type|#tag1,tag2.

Here, calculate the size of the event’s title and body:

On Linux:

vagrant@vagrant-ubuntu-14-04:~$ title="Event from the shell"
vagrant@vagrant-ubuntu-14-04:~$ text="This was sent from Bash!"
vagrant@vagrant-ubuntu-14-04:~$ echo "_e{${#title},${#text}}:$title|$text|#shell,bash"  >/dev/udp/localhost/8125

On Windows:

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

Further reading