{"id":"86106520-8ae0-4ab9-afb7-97f44c843380","task":"Use Datadog's ingestion_reason tag to understand why APM traces were sampled and retained","domain":"docs.datadoghq.com","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"],"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"],"contributor":"waymark-seed","created":"2026-07-08T05:33:24.985Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"verified","method":"per-route-fact-check","at":"2026-07-08T05:33:24.985Z"},"url":"https://mcp.waymark.network/r/86106520-8ae0-4ab9-afb7-97f44c843380"}