Network Performance Monitoring is now generally available! Network Monitoring is now available!

DogStatsD

The easiest way to get your custom application metrics into Datadog is to send them to DogStatsD, a metrics aggregation service bundled with the Datadog Agent. DogStatsD implements the StatsD protocol and adds a few Datadog-specific extensions:

  • Histogram metric type
  • Service checks
  • Events
  • Tagging

Any compliant StatsD client works with DogStatsD and the Agent, but you won’t be able to use the Datadog-specific extensions.

Note: DogStatsD does NOT implement Timers from StatsD as a native metric type (though it does support them via histograms).

How it works

DogStatsD accepts custom metrics, events, and service checks over UDP and periodically aggregates and forwards them to Datadog.

Because it uses UDP, your application can send metrics to DogStatsD and resume its work without waiting for a response. If DogStatsD ever becomes unavailable, your application won’t experience an interruption.

As it receives data, DogStatsD aggregates multiple data points for each unique metric into a single data point over a period of time called the flush interval (ten seconds, by default).

Setup

DogStatsD is enabled by default over UDP port 8125 for Agent v6+. If you don’t need to change this port, see directly how to setup DogStatsD in your code. Also see relevant DogStatsD setup documentation for Docker and Kubernetes.

Agent

By default, DogStatsD listens on UDP port 8125. If you need to change this, configure the dogstatsd_port option in the main Agent configuration file, and restart the Agent. You can also configure DogStatsD to use a Unix domain socket. To enable a custom Agent DogStatsD server UDP port:

  1. Edit your datadog.yaml file to un-comment the use_dogstatsd and dogstatsd_port parameters:

    ## @param use_dogstatsd - boolean - optional - default: true
    ## Set this option to false to disable the Agent DogStatsD server.
    #
    use_dogstatsd: true
    
    ## @param dogstatsd_port - integer - optional - default: 8125
    ## Override the Agent DogStatsD port.
    ## Note: Make sure your client is sending to the same UDP port.
    #
    dogstatsd_port: 8125
  2. Restart your Agent.

Code

Install the DogStatsD client

Official Datadog-DogStatsD client libraries are available for the following languages. You can use any generic StatsD client to send metrics to DogStatsD, but you won’t be able to use any of the Datadog-specific features mentioned above:

$ pip install datadog
$ gem install dogstatsd-ruby
$ go get github.com/DataDog/datadog-go/statsd

The Java DataDog StatsD Client is distributed with maven central, and can be downloaded from Maven. Start by adding the following configuration to your pom.xml:

<dependency>
    <groupId>com.datadoghq</groupId>
    <artifactId>java-dogstatsd-client</artifactId>
    <version>2.8</version>
</dependency>

Add the following to your composer.json:

"datadog/php-datadogstatsd": "1.4.*"

Note: The first version shipped in Composer is 0.0.3

Or manually clone the repository at github.com/DataDog/php-datadogstatsd and set it up with require './src/DogStatsd.php'.

Instantiate the DogStatsD client

Once your DogStatsD client is installed, instantiate it in your code:

from datadog import statsd

options = {
    'statsd_host':'127.0.0.1',
    'statsd_port':8125
}

initialize(**options)
# Import the library
require 'datadog/statsd'

# Create a DogStatsD client instance.
statsd = Datadog::Statsd.new('localhost', 8125)
dogstatsd_client, err := statsd.New("127.0.0.1:8125")
if err != nil {
    log.Fatal(err)
}

For more options, see Datadog’s GoDoc.

import com.timgroup.statsd.NonBlockingStatsDClient;
import com.timgroup.statsd.StatsDClient;

public class DogStatsdClient {

    public static void main(String[] args) throws Exception {

        StatsDClient Statsd = new NonBlockingStatsDClient("statsd", "localhost", 8125);

    }
}

Instantiate a new DogStatsd object using composer:

<?php

require __DIR__ . '/vendor/autoload.php';

use DataDog\DogStatsd;

$statsd = new DogStatsd(
    array('host' => '127.0.0.1',
          'port' => 8125,
     )
  );

Configure the DogStatsd class:

// The code is located under the StatsdClient namespace
using StatsdClient;

// ...

var dogstatsdConfig = new StatsdConfig
{
    StatsdServerName = "127.0.0.1",
    StatsdPort = 8125,
};

StatsdClient.DogStatsd.Configure(dogstatsdConfig);

Client instantiation parameters

In addition to the required DogStatsD configuration (url and port), the following optional parameters are available for your DogStatsD client:

ParameterTypeDefaultDescription
statsd_hostStringlocalhostThe host of your DogStatsD server.
statsd_portInteger8125The port of your DogStatsD server.
statsd_socket_pathStringnullThe path to the DogStatsD Unix domain socket (overrides host and port, only supported with the Agent v6+).
statsd_constant_tagsList of stringsnullTags to apply to all metrics, events, and service checks.
statsd_namespaceStringnullNamespace to prefix all metrics, events, and service checks.

For more information, see the DogStatsD module documentation.

ParameterTypeDefaultDescription
hostStringlocalhostThe host of your DogStatsD server.
portInteger8125The port of your DogStatsD server.
socket_pathStringnullThe path to the DogStatsD Unix domain socket (overrides host and port, only supported with the Agent v6+).
tagsList of stringsnullTags to apply to all metrics, events, and service checks.
namespaceStringnullNamespace to prefix to all metrics, events, and service checks.
ParameterTypeDescription
NamespaceStringNamespace to prefix to all metrics, events, and service checks.
TagsList of stringsGlobal tags applied to every metric, event, and service check.
BufferedBooleanUsed to pack multiple DogStatsD messages in one payload. When set to true, messages are buffered until the total size of the payload exceeds MaxMessagesPerPayload or 100ms after the payload started building.
MaxMessagesPerPayloadIntegerThe maximum number of metrics, events, and/or service checks a single payload can contain. This option only takes effect when the client is buffered.
AsyncUDSBooleanUsed to switch between async and blocking mode for UDS. Blocking mode allows for error checking but does not guarantee that calls won’t block the execution.
WriteTimeoutUDSIntegerThe timeout after which a UDS packet is dropped.

For more options, see Datadog’s GoDoc.

ParameterTypeDescription
prefixStringThe prefix to apply to all metrics, events, and service checks.
hostnameStringThe host name of the targeted StatsD server.
portIntegerThe port of the targeted StatsD server.
constantTagsList of stringsGlobal tags to be applied to every metric, event, and service check.

For more information, see the NonBlockingStatsDClient Class documentation.

ParameterTypeDefaultDescription
hostStringlocalhostThe host of your DogStatsD server. If this is not set the Agent looks at the DD_AGENT_HOST environment variable.
portInteger8125The port of your DogStatsD server. If this is not set, the Agent looks at the DD_DOGSTATSD_PORT environment variable.
socket_pathStringnullThe path to the DogStatsD Unix domain socket (overrides host and port). This is only supported with Agent v6+.
global_tagsList of StringsnullTags to apply to all metrics, events, and service checks. The @dd.internal.entity_id tag is appended to global_tags from the DD_ENTITY_ID environment variable.
ParameterTypeDefaultDescription
StatsdServerNameStringlocalhostThe host name of the targeted StatsD server.
StatsdPortInteger8125The port of the targeted StatsD server.
PrefixStringnullPrefix to apply to every metric, event, and service check.
ConstantTagsList of stringsnullGlobal tags to be applied to every metric, event, and service check.

Dive into DogStatsD

DogStatsD and StatsD are broadly similar, however, DogStatsD contains advanced features which are specific to Datadog, including available data types, events, service checks, and tags:


If you’re interested in learning more about the datagram format used by DogStatsD, or want to develop your own Datadog library, see the datagram and shell usage section, which also explains how to send metrics and events straight from the command line.