DogStatsD and Custom Metrics
Key Takeaways
- DogStatsD is the Agent's local listener for custom metrics, events, and service checks — default UDP port 8125 on localhost.
- Applications send telemetry to the local Agent via DogStatsD so the Agent aggregates and forwards efficiently instead of each app calling Datadog's HTTP API.
- DogStatsD supports count, gauge, histogram, and distribution metric types; count submissions normalize over the Agent flush interval.
- Unix Domain Socket (UDS) is an alternative to UDP when client and Agent share the same host and the library supports it.
- Containerized senders outside localhost require enabling non-local DogStatsD traffic and ensuring UDP 8125 is reachable.
Quick Answer: DogStatsD is the Datadog Agent's local ingestion service for custom metrics, events, and service checks. By default it listens on UDP port 8125 on localhost. Application code sends lightweight datagrams to the Agent, which batches and forwards them to Datadog — far more efficient than posting every point to the HTTP API.
Data Collection is the largest domain on the Datadog Fundamentals outline (~21% of topics). DogStatsD sits at the center because most teams eventually need application-level telemetry that built-in integrations do not emit: checkout completions, queue depth, cache hit ratio, or feature-flag evaluations. The exam tests whether you understand what DogStatsD does, how it connects to the Agent, and when to choose it over API submission.
What DogStatsD Does
DogStatsD implements a StatsD-compatible protocol extended by Datadog. Your application (or a client library in Python, Java, Go, Ruby, Node.js, and others) formats a metric line and sends it to the Agent's DogStatsD server. The Agent enriches the data with host tags, applies type-specific handling, and ships it to Datadog intake along with other Agent-collected telemetry.
| Component | Role |
|---|---|
| Application / script | Emits business or app KPIs via a DogStatsD client library |
| DogStatsD server | Listens locally on the Agent (UDP 8125 by default) |
| Datadog Agent | Aggregates, tags, and forwards to Datadog |
| Datadog platform | Stores timeseries, powers Metrics Explorer, dashboards, monitors |
On the Exam: DogStatsD is for custom telemetry from code running near the Agent. It is not how cloud-provider metrics (AWS CloudWatch, Azure Monitor) arrive — those use integrations and crawlers covered in the next section.
Default Port, Protocol, and Transports
| Setting | Default | Notes |
|---|---|---|
| Port | 8125 | UDP |
| Bind address | localhost (127.0.0.1) | Limits exposure to local processes |
| Alternative transport | Unix Domain Socket (UDS) | Same-host only; supported when client library allows |
UDP is fire-and-forget: the application does not wait for an HTTP round trip, which keeps overhead low under high emit rates. If you change the DogStatsD port in Agent configuration, every sending application must match.
Container and Non-Local Traffic
By default, DogStatsD accepts traffic only from localhost. In Kubernetes or Docker, an app container often cannot reach the Agent's loopback interface. The fix is documented Agent configuration to enable non-local traffic and expose UDP 8125 so sibling containers or the host network can reach the listener. This is a frequent exam scenario: "metrics work on the host but not from a sidecar container."
Metric Types Submitted via DogStatsD
DogStatsD accepts the same conceptual types Datadog uses elsewhere:
| Type | Typical Use | Exam Note |
|---|---|---|
| Gauge | Current value (queue size, temperature) | Reported as-is at flush time |
| Count | Incrementing events (requests served) | Normalized over flush interval; may display as a per-second decimal |
| Histogram | Distribution of values (latency samples) | Agent aggregates before forwarding |
| Distribution | Global percentile accuracy | Preferred for latency percentiles at scale |
| Set | Unique occurrences (unique users) | Counts distinct values per flush |
| Event | Discrete occurrences with title/text | Appears in Event Stream |
| Service check | Pass/warn/fail status | Powers integration health views |
Common Trap: A DogStatsD count showing a decimal per-second value is expected behavior, not a broken gauge. Counts are normalized over the Agent flush interval.
Why Send to the Agent Instead of the API?
Three reasons dominate production design — and exam answers:
- Low overhead — UDP or UDS avoids TLS handshakes and HTTP headers on every emission.
- Local aggregation — the Agent can batch many points into fewer outbound payloads.
- Consistent tagging — host-level and global tags from
datadog.yamlattach automatically.
Direct HTTP API submission (/api/v1/series) is valid when no Agent is available (serverless functions, external cron jobs) but is heavier per point. DogStatsD is the default recommendation for long-running apps on hosts or containers with a nearby Agent.
Configuration Touchpoints
Relevant Agent settings live in datadog.yaml and environment variables:
| Setting | Purpose |
|---|---|
dogstatsd_port | Change listening port from 8125 |
dogstatsd_non_local_traffic | Allow non-localhost senders |
dogstatsd_socket | Enable UDS path |
DD_DOGSTATSD_PORT | Environment-variable equivalent |
Global tags defined in datadog.yaml apply to DogStatsD submissions, so env:prod on the host tags every custom metric without repeating it in application code.
Worked Scenario: E-Commerce Checkout Metric
A retail team wants orders.completed tagged by payment_method. Their API servers run in Kubernetes pods; the Datadog Agent runs as a DaemonSet.
- Enable non-local DogStatsD on the Agent DaemonSet.
- Point the Python
datadoglibrary at the node's Agent IP and port 8125. - On each successful checkout:
statsd.increment('orders.completed', tags=['payment_method:card']). - Verify in Metrics Explorer within one to two minutes.
If they posted directly to the API from every pod, they would need API keys in each container, handle retries, and generate far more outbound HTTPS traffic.
DogStatsD vs Agent Integrations
| Signal Source | Collection Path |
|---|---|
| MySQL, Nginx, Redis (packaged check) | Agent integration in conf.d/ |
| Custom app KPI | DogStatsD from application code |
| AWS RDS CPU | Cloud integration crawler (no local Agent on RDS) |
Knowing which path applies prevents misconfigured troubleshooting — a MySQL integration issue is not fixed by changing DogStatsD port.
Events and Service Checks via DogStatsD
Beyond numeric metrics, DogStatsD accepts events (title, text, alert type, tags) and service checks (OK, warning, critical status with a check name). Service checks power integration-style health views for custom dependencies — for example, reporting CRITICAL when your app cannot reach a payment gateway. The exam may group these under DogStatsD capabilities even though they are not timeseries metrics.
What is DogStatsD primarily used for on a host running the Datadog Agent?
By default, which port and protocol does DogStatsD use?
A containerized application cannot reach DogStatsD on 127.0.0.1 inside the Agent container. What is the most likely fix?
Besides UDP, what transport can DogStatsD use when the client and Agent are on the same host?