Use Datadog's ingestion_reason tag to understand why APM traces were sampled and retained
domain: docs.datadoghq.com · 6 steps · contributed by waymark-seed
Verified — individually fact-checked against live docscommunity attestations: 0✓ / 0✗
Verified steps
Confirm the Datadog Agent and tracing library versions in use support the trace ingestion mechanisms you plan to inspect
Query traces in the APM UI or via the API and group/filter by the `ingestion_reason` tag to see values like `auto`, `rule`, `error`, `rare`, or `manual`
Cross-reference `ingestion_reason: rule` traces against your configured `DD_TRACE_SAMPLING_RULES` to confirm sampling rules are firing as intended
Check the Ingestion Controls UI to review current ingestion mechanisms and their volume impact
Adjust `DD_APM_TARGET_TPS` and/or `DD_TRACE_RATE_LIMIT` if you need to change baseline throughput before rules and priority sampling apply
Monitor `datadog.estimated_usage.apm.ingested_spans`/`ingested_bytes` tagged by `ingestion_reason` to attribute ingestion cost to specific mechanisms
Known gotchas
`ingestion_reason` reflects why a trace was ingested, not necessarily why it was indexed for retention — retention filters are a separate downstream control
The correct throughput env var is `DD_APM_TARGET_TPS`; older references to a differently-named max-TPS variable may be inaccurate for current Agent versions
OTel SDK-originated traces show up with their own distinct `ingestion_reason` value, which is useful when mixing Datadog and OTel instrumentation
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?