Retention Filter
A retention filter is a rule that decides, by tag conditions and a retention rate, which of the spans ingested by Datadog APM are kept in the index that is searchable for 15 days (Indexed Spans). It works at a different stage from Ingestion Controls, which limit the amount sent.
Overview
A retention filter is a rule that sorts spans arriving at Datadog into "keep in the index" or "do not keep." Each filter has a query of tag conditions and a retention rate of 0 to 100%, and of the spans matching the conditions, the retention rate's share enters the 15-day index and becomes searchable in the Trace Explorer. It is composed of three layers: the Intelligent Retention Filter that Datadog runs at all times, the default filter that keeps errors, and the custom filters you create yourself. The situations where you care about it are when you are stuck with "I cannot find that trace" during an incident investigation, when billing increases beyond the Indexed Spans allotment, and when you decide that important transactions must always be kept.
A rule that selects which ingested spans to keep for 15 days
A retention filter is a rule that decides which of the spans ingested into Datadog APM go into the index that is retained for 15 days. The official documentation explains that after ingestion, spans are "retained for 15 days according to the retention filters set on the account" (as of September 2026, Source: Trace Retention). One filter consists of a name, a query with tag conditions, and a retention rate indicating what percentage of the spans matching the conditions to put in the index; the retained spans are selected uniformly from those that match. Spans that enter the index can be used from the Trace Explorer, dashboards, and monitors for 15 days. Only the diversity sampling portion of the Intelligent Retention Filter remains for 30 days. Creating or modifying filters requires the apm_retention_filter_write permission.
The amount sent and the amount kept are decided at different stages
There are two gates before a span becomes searchable. The upstream Ingestion Controls decide how much to send to Datadog, and the downstream retention filters decide how much of what was sent to keep in the index.
- The application generates spans
- Ingestion Controls: Agent and tracer settings decide the share sent to Datadog (amount sent)
- Retention filters: sort the arriving spans by tag conditions and retention rate (amount kept)
- Indexed Spans: the selected spans enter the 15-day index and become the target of search and aggregation
If you do not think of these 2 stages separately, you will be puzzled by mismatches such as the Indexed Spans cost not changing even though you reduced the amount sent, or the trace from an incident not being found even though you send everything. The upstream mechanism is left to the Ingestion Controls entry; here we cover only the downstream stage.
Three layers of filters - the always-on ones and the ones you create
The official documentation explains retention filters in three layers (as of September 2026, Source: Trace Retention).
| Layer | What it keeps | Indexed Spans usage |
|---|---|---|
| Intelligent Retention Filter (always on) | Diversity sampling = at least 1 span every 15 minutes per combination of environment / service / operation / resource, high-latency p75 / p90 / p95, and representative errors, for 30 days. In addition, uniform 1% sampling keyed on trace_id, and traces linked to 1% of RUM sessions | Not counted (no effect on billing) |
| Default filters | Error Default keeps spans with status:error (query and retention rate can be changed / it can also be disabled). If you use App and API Protection / Synthetics / Dynamic Instrumentation, each of their defaults is also active | Counted |
| Custom filters | Set a span rate, the percentage of matching spans to keep, on a query of arbitrary span tags or attributes. Optionally, a trace rate, the percentage for keeping the whole trace, can also be set | Counted. The trace rate can greatly increase usage |
Filters are evaluated in order from the top, and spans kept by an upstream filter do not appear in the edit screen of downstream filters. The reason a span was kept goes into the span's retained_by attribute and can be distinguished by the values retention_filter / trace_retention_filter / diversity_sampling / flat_sampled. This attribute is the entry point for confirming "why was this trace kept."
How it affects the allotment and billing
Indexed Spans have an allotment. On the official pricing page as of August 2026, 1 million spans per month (15-day retention) are included per APM host, pooled across all hosts (Source: Datadog Pricing). This article explains how billing works. For current unit prices and plans, refer to Datadog's official pricing page. The official documentation states explicitly that spans kept by the Intelligent Retention Filter are not counted toward this usage and do not affect billing (as of September 2026, Source: Trace Retention). What moves usage is the default and custom filters; in particular, the trace rate puts even parent and child spans that do not match the conditions into the index, so it is warned that usage can increase greatly. When creating or modifying a filter, an estimate of how many percent the indexed volume will change is displayed, so the habit of looking at this number before saving prevents cost accidents. The unit price for the portion beyond the allotment and the estimation procedure are left to How Datadog APM pricing works.
Spans left out of the index have not disappeared
Spans that did not enter the index because of the filters are merely excluded from search. When you open an indexed span in the Trace Explorer, the flame graph shows the full trace context even if the parent and child spans of the same trace are not indexed (as of September 2026, Source: Trace Retention). Remembering the two scopes separately, that only indexed spans are found by search and that the whole trace can be read once found, keeps you from getting lost during an investigation. The circumstances under which the spans you sent and the spans you can later search are decided separately are left to the span entry. There is also one mix-up in the opposite direction. Spans kept by the Intelligent Retention Filter are excluded from the evaluation of APM trace analytics monitors. Conditions you want to count in a monitor must be kept explicitly by your own custom filter. Not designing distributed tracing on the assumption of "keep everything," and deciding the keep rules first, is the way to live with this mechanism.