DogStatsD

Active contributors: Olivier G, Pierre Gimalac, Rémy Mathieu, maxime mouial, Gustavo Caso

Purpose

DogStatsD is Datadog's StatsD-compatible server. It accepts custom application metrics, events, and service checks over UDP, Unix Datagram Socket, or Windows named pipe. After parsing and normalization it pushes MetricSamples into the Agent's aggregator pipeline.

DogStatsD comes in two forms:

• Embedded in the core agent binary (the default deployment). Same code path, same component bundle.
• Standalone as cmd/dogstatsd/, useful when only StatsD ingestion is needed (e.g., an isolated DogStatsD container).

Directory layout

cmd/dogstatsd/
├── main_nix.go         # Linux/macOS entrypoint
├── main_windows.go     # Windows entrypoint
├── command/            # Root cobra command
├── subcommands/        # `start` subcommand
├── dist/               # Default config
├── README.md           # Public introduction
└── windows_resources/

comp/dogstatsd/         # The actual DogStatsD component bundle
├── bundle.go           # Fx options
├── config/             # Config bindings
├── constants/          # Shared constants
├── http/               # Embedded HTTP API for the standalone binary
├── listeners/          # UDP, UDS, named pipe, capture replay
├── mapper/             # Metric mapper for StatsD pattern → Datadog metric
├── packets/            # Packet pool, batching
├── pidmap/             # Maps source PIDs to container/origin tags
├── replay/             # Capture replay implementation
├── server/             # The packet → MetricSample pipeline
├── serverDebug/        # Server-side debug introspection
├── statsd/             # Internal stats emission
└── status/             # Status provider

Pipeline

graph LR
    UDP[UDP listener<br/>comp/dogstatsd/listeners/udp] --> POOL[Packet pool]
    UDS[UDS listener<br/>listeners/uds_*] --> POOL
    PIPE[Named pipe listener<br/>listeners/win_named_pipe] --> POOL
    REPLAY[Replay listener<br/>listeners/replay] --> POOL
    POOL -->|batched packets| PARSE[Parser<br/>server/parse.go]
    PARSE -->|MetricSample| DEMUX[Demultiplexer<br/>comp/aggregator/demultiplexer]
    DEMUX -->|TimeSampler| AGG[Aggregator]
    AGG --> SER[Serializer]
    SER --> FWD[Forwarder]

The listeners are protocol-specific but feed a shared packet pool. Worker goroutines pull batches and parse them through server/parse.go, producing typed metric samples. Origin detection (pidmap/) attaches the source container's tags via the tagger so per-container tagging works without explicit client tagging.

The aggregator then handles dedup, sampling, and percentile aggregation before the serializer emits a Series payload.

Configuration knobs

DogStatsD is one of the most configurable parts of the Agent. Notable knobs in datadog.yaml (and their DD_* env equivalents):

Key	Effect
dogstatsd_port	UDP port (default 8125, 0 to disable)
dogstatsd_socket	UDS path (Linux/macOS)
dogstatsd_pipe_name	Windows named pipe
dogstatsd_buffer_size	UDP buffer size
dogstatsd_non_local_traffic	Listen on non-loopback addresses
dogstatsd_origin_detection	Resolve origin from cgroup or UID
dogstatsd_origin_detection_unified	Newer unified origin protocol
dogstatsd_metrics_stats_enable	Internal per-metric stats
dogstatsd_eol_required	Require newline-terminated packets
dogstatsd_no_aggregation_pipeline	Skip aggregation (forwarding mode)
histogram_aggregates, histogram_percentiles	Per-histogram aggregation knobs

The pkg/config/setup/dogstatsd.go file has the canonical defaults.

Subcommands and tooling

The DogStatsD-related subcommands live on the core Agent:

Subcommand	Purpose
agent dogstatsd-stats	Per-metric statistics
agent dogstatsd-capture	Capture incoming packets to a file
agent dogstatsd-replay	Replay a captured file into the local DogStatsD server
dogstatsd start	Standalone binary's only meaningful subcommand

Capture/replay (comp/dogstatsd/replay/) is invaluable when reproducing a customer issue: capture for a few seconds, ship the file, replay locally.

Mapping

comp/dogstatsd/mapper/ implements the DogStatsD mapper: regex-based rewriting of incoming metric names, useful when integrating with applications that use a different metric naming convention. Mapping rules live in datadog.yaml under dogstatsd_mapper_profiles.

Origin detection

For containerized deployments DogStatsD enriches metrics with the source container's tags. Multiple resolution paths exist:

• cgroup parsing on Linux from the source pid (pkg/util/containers/).
• Datadog client tagging when the SDK includes a c:<container_id> tag.
• Unified origin detection (newer): the SDK sends a binary header containing the cgroup inode.
• External Data: a header with cluster-name, namespace, and pod that the Cluster Agent relays.

The origin then routes through the tagger to produce a stable set of tags applied to every sample from that source.

Listeners

Each listener has its own file under comp/dogstatsd/listeners/:

Listener	File	Used on
UDP	listener_udp.go	All platforms
UDS datagram	listener_uds_datagram_*.go	Linux/macOS
UDS stream	listener_uds_stream_*.go	Linux/macOS
Windows named pipe	listener_win_named_pipe.go	Windows
Replay	listener_replay.go	Tests / capture replay

UDS streams are newer and avoid datagram fragmentation issues.

Standalone binary

cmd/dogstatsd/ produces a slim binary that wires only the DogStatsD bundle and a forwarder. It is useful as a sidecar or a host-level packet shipper that does not need check execution.

Key abstractions

Type / package	File	Description
dogstatsd.Component	comp/dogstatsd/server/def/component.go	Top-level DogStatsD interface
Listener	comp/dogstatsd/listeners/listener.go	Listener abstraction (UDP/UDS/pipe/replay)
Packet	comp/dogstatsd/packets/packet.go	Buffer pool entry
Parser	comp/dogstatsd/server/parse.go	StatsD line parser
Mapper	comp/dogstatsd/mapper/mapper.go	Pattern-based metric renaming

Entry points for modification

• New listener (e.g., a new transport): implement Listener and register it in bundle.go.
• New origin-detection scheme: extend pidmap/ and the parser's metadata extraction.
• New mapping rule type: extend mapper/.
• A new metric type from the StatsD line: add it to the parser and the corresponding aggregator handler in pkg/aggregator/.

Related pages

• Apps: Agent — DogStatsD lives inside the core Agent by default.
• Systems: Aggregator pipeline — what happens after the parser.
• Features: Metrics pipeline — end-to-end metric story.