DogStatsD

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.

By default, DogStatsD listens on UDP port 8125, so you need to bind this port to your host port when running the Agent in a container. If your StatsD metrics come from outside of localhostyou must set DD_DOGSTATSD_NON_LOCAL_TRAFFIC to true to allow metric collection. In order to run the Agent with the DogStatsd server up, execute the following command:

DOCKER_CONTENT_TRUST=1 \
docker run -d -v /var/run/docker.sock:/var/run/docker.sock:ro \
              -v /proc/:/host/proc/:ro \
              -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
              -e DD_API_KEY="<DATADOG_API_KEY>" \
              -e DD_DOGSTATSD_NON_LOCAL_TRAFFIC="true" \
              -p 8125:8125/udp \
              gcr.io/datadoghq/agent:latest

If you need to change the port used to collect StatsD metrics, use the DD_DOGSTATSD_PORT="<NEW_DOGSTATSD_PORT> environment variable. You can also configure DogStatsD to use a Unix domain socket:

To start collecting your StatsD metrics, you need to bind the DogStatsD port to a host port. You can also configure DogStatsD to use a Unix domain socket.

1. Add a hostPort to your datadog-agent.yaml manifest:

   ports:
       - containerPort: 8125
         hostPort: 8125
         name: dogstatsdport
         protocol: UDP
   

   This enables your applications to send metrics via DogStatsD on port 8125 on whichever node they happen to be running.

   Note: hostPort functionality requires a networking provider that adheres to the CNI specification, such as Calico, Canal, or Flannel. For more information, including a workaround for non-CNI network providers, consult the Kubernetes documentation.

2. Enable DogStatsD non local traffic to allow StatsD data collection, set DD_DOGSTATSD_NON_LOCAL_TRAFFIC to true in your datadog-agent.yaml manifest:

   - name: DD_DOGSTATSD_NON_LOCAL_TRAFFIC
     value: 'true'
   

   This allows collecting StatsD data from other containers than the one running the Agent.

3. Apply the change:

   kubectl apply -f datadog-agent.yaml
   

Warning: The hostPort parameter opens a port on your host. Make sure your firewall only allows access from your applications or trusted sources. Another word of caution: some network plugins don’t support hostPorts yet, so this won’t work. The workaround in this case is to add hostNetwork: true in your Agent pod specifications. This shares the network namespace of your host with the Datadog Agent. It also means that all ports opened on the container are also opened on the host. If a port is used both on the host and in your container, they conflict (since they share the same network namespace) and the pod will not start. Not all Kubernetes installations allow this.

Send StatsD metrics to the Agent

Your application needs now a reliable way to determine the IP address of its host. This is made simple in Kubernetes 1.7, which expands the set of attributes you can pass to your pods as environment variables. In versions 1.7 and above, you can pass the host IP to any pod by adding an environment variable to the PodSpec. For instance, your application manifest might look like this:

env:
    - name: DD_AGENT_HOST
      valueFrom:
          fieldRef:
              fieldPath: status.hostIP

With this, any pod running your application is able to send DogStatsD metrics via port 8125 on $DD_AGENT_HOST.

Note: As a best practice, Datadog recommends using unified service tagging when assigning attributes. Unified service tagging ties Datadog telemetry together through the use of three standard tags: env, service, and version. To learn how to unify your environment, refer to the dedicated [unified service tagging][8] documentation.

Origin detection over UDP

Origin detection is supported in Agent 6.10.0+ and allows DogStatsD to detect where the container metrics come from, and tag metrics automatically. When this mode is enabled, all metrics received via UDP are tagged by the same container tags as Autodiscovery metrics.

Note: An alternative to UDP is Unix Domain Sockets.

To enable origin detection over UDP, add the following lines to your application manifest:

env:
    - name: DD_ENTITY_ID
      valueFrom:
          fieldRef:
              fieldPath: metadata.uid

To set tag cardinality for the metrics collected using origin detection, set the environment variable DD_DOGSTATSD_TAG_CARDINALITY to either low (default) or orchestrator.

Note: For UDP, pod_name tags are not added by default to avoid creating too many custom metrics.

To gather custom metrics with DogStatsD with helm:

1. Update your datadog-values.yaml file to enable DogStatsD:

     dogstatsd:
       port: 8125
       useHostPort: true
       nonLocalTraffic: true
   

   Note: hostPort functionality requires a networking provider that adheres to the CNI specification, such as Calico, Canal, or Flannel. For more information, including a workaround for non-CNI network providers, consult the Kubernetes documentation. The hostPort parameter opens a port on your host. Make sure your firewall only allows access from your applications or trusted sources. Another word of caution: some network plugins don’t support hostPorts yet, so this won’t work. The workaround in this case is to add hostNetwork: true in your Agent pod specifications. This shares the network namespace of your host with the Datadog Agent. It also means that all ports opened on the container are also opened on the host. If a port is used both on the host and in your container, they conflict (since they share the same network namespace) and the pod will not start. Not all Kubernetes installations allow this.

2. Upgrade your Agent configuration:

   helm upgrade -f datadog-values.yaml <RELEASE_NAME> datadog/datadog
   

3. Update your application pods: Your application needs now a reliable way to determine the IP address of its host. This is made simple in Kubernetes 1.7, which expands the set of attributes you can pass to your pods as environment variables. In versions 1.7 and above, you can pass the host IP to any pod by adding an environment variable to the PodSpec. For instance, your application manifest might look like this:

   env:
       - name: DD_AGENT_HOST
         valueFrom:
             fieldRef:
                 fieldPath: status.hostIP
   

   With this, any pod running your application is able to send DogStatsD metrics via port 8125 on $DD_AGENT_HOST.

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.10.1</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'.

Get the package from NuGet to install it.

dogstatsd_client, err := statsd.New("127.0.0.1:8125")
if err != nil {
    log.Fatal(err)
}

For more options, see Datadog’s GoDoc.

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,
};

using (var dogStatsdService = new DogStatsdService())
{
    dogStatsdService.Configure(dogstatsdConfig);
    // ...
} // Flush metrics not yet sent

For more information, see the DogStatsD module documentation.

For more options, see Datadog’s GoDoc.

For more information, see the NonBlockingStatsDClient Class documentation.