If you need to change the port, 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. Set the dogstatsd_port parameter:

   ## @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 run -d --cgroupns host \
              --pid host \
              -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 \
              registry.datadoghq.com/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.

StatsD metrics collection is enabled by default on UNIX domain socket. To start collecting your StatsD metrics over UDP, you need to activate the DogStatsD feature in the Operator settings.

1. Add features.dogstatsd.hostPortConfig.enabled to your datadog-agent.yaml manifest:

   features:
       dogstatsd:
           hostPortConfig:
               enabled: true
   

   This is an example datadog-agent.yaml manifest:

   apiVersion: datadoghq.com/v2alpha1
   kind: DatadogAgent
   metadata:
     name: datadog
   spec:
     global:
       credentials:
         apiSecret:
           secretName: datadog-secret
           keyName: api-key
     features:
       dogstatsd:
         hostPortConfig:
           enabled: true
   

   This enables the Agent to collect StatsD metrics over UDP on port 8125.

2. Apply the change:

   kubectl apply -f datadog-agent.yaml
   

Warning: The features.dogstatsd.hostPortConfig.hostPort parameter opens a port on your host. Make sure your firewall only allows access from your applications or trusted sources. If your network plugin doesn’t support hostPorts, so 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 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 does not start. Some Kubernetes installations do not allow this.

Send StatsD metrics to the Agent

Your application needs 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 with 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, see unified service tagging.

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, see the Kubernetes documentation: HostPort services do not work.

   Warning: The hostPort parameter opens a port on your host. Make sure your firewall only allows access from your applications or trusted sources. If your network plugin doesn’t support hostPorts, so 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 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 does not start. Some Kubernetes installations do not 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 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 through port 8125 on $DD_AGENT_HOST.

On Linux, the container ID can be extracted from procfs entries related to cgroups. The client reads from /proc/self/cgroup or /proc/self/mountinfo to attempt to parse the container ID.

In cgroup v2, the container ID can be inferred by resolving the cgroup path from /proc/self/cgroup, combining it with the cgroup mount point from /proc/self/mountinfo. The resulting directory’s inode is sent to the Datadog Agent. If the Datadog Agent is on the same node as the client, this information can be used to identify the pod’s UID.

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

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

The DogStatsD client attaches an internal tag, entity_id. The value of this tag is the content of the DD_ENTITY_ID environment variable, which is the pod’s UID.

Add the following label to your pod:

admission.datadoghq.com/enabled: "true"

If your pod has this label, the Admissions Controller injects an environment variable, DD_EXTERNAL_ENV. The value of this variable is sent in a field with the metric, which can be used by the Datadog Agent to determine the metric’s origin.