Indexed Spans
Indexed Spans are the spans ingested into Datadog APM that a retention filter selected and kept in a searchable index for 15 days. They are the raw material for search, aggregation, and monitors, and they are also the unit in which usage is counted by number of spans.
Overview
Indexed Spans are the spans that retention filters selected from everything Datadog APM ingested and kept in a 15-day index. Spans that were merely ingested are still used to display a whole trace, but only spans that made it into the index can be used for Trace Explorer search and aggregation and for evaluating trace analytics monitors. This is the concept you start from when you investigate spans that do not show up in search or when you look into overage against your allotment, because it tells you which filter is keeping what.
Spans selected and kept at the later stage of ingestion
Indexed Spans are the spans ingested into Datadog APM that a retention filter selected and kept in a searchable index for 15 days. APM spans pass through two gates. The earlier gate, Ingestion Controls, decides how much the Agent sends, and the later gate, retention filters, decides what to keep from what arrived. Indexed Spans are the result of this later gate and do not include spans that were merely ingested. The official documentation also states explicitly that retention filters do not affect how much the Agent collects and sends, and that you should use Ingestion Controls if you want to control the volume sent (as of September 2026, Source: Trace Retention).
- An instrumented application generates spans
- Ingestion Controls decide how much is sent (Ingested Spans, counted in GB)
- Retention filters select what to keep using tag conditions and retention rates
- Spans enter the 15-day index as Indexed Spans (counted by number of spans)
The rules for what gets kept are left to the entry on retention filters; this entry covers what you can do with the spans that were kept and what gets counted.
What you can and cannot do once a span is in the index
Spans in the index can be searched in Trace Explorer, appear in the timeseries, top list, and table aggregation views, can be used in dashboard and notebook queries, and are evaluated by trace analytics monitors. This state lasts for 15 days (as of September 2026, Source: Trace Retention). The easy thing to miss is the difference between display and search. If you open a span that is in the index, the whole trace is displayed even when its parent and child spans are not in the index, but search only finds the spans that retention filters put into the index. This is the true cause of the "I can see it but it does not come up in search" phenomenon. Monitors also have two exclusions. Spans kept by the Intelligent Retention Filter are excluded from trace analytics monitor evaluation, and spans that entered the index indirectly through a trace-level filter are not evaluated either. Spans you want to monitor should match the conditions of your own filter directly.
The retained_by attribute answers why a span was kept
Every span kept in the index carries a retained_by attribute that shows which mechanism kept it. The measured usage is available in the datadog.estimated_usage.apm.indexed_spans metric. The Spans Indexed column on the Retention Filters page is also based on this value (as of September 2026, Source: Trace Retention).
| Value | Mechanism that kept the span | Usage |
|---|---|---|
retention_filter | Default or custom filter (no trace rate). Not included in Trace Queries | Counted |
trace_retention_filter | Filter with a trace rate configured | Counted |
diversity_sampling | Diversity sampling by the Intelligent Retention Filter | Not counted |
flat_sampled | Uniform 1% sampling. Can be split into @retention_reason:rum (linked to RUM sessions) and @retention_reason:trace (based on trace_id) | Not counted |
When the index count is higher than expected, the quickest check is to break the count down by retained_by in Trace Explorer. What remains after you exclude the two kinds that are not counted is the usage your own filter design produced.
Two ways to keep spans: span-level and trace-level
There are two kinds of filter: span-level filters, which put only the matching spans into the index, and trace-level filters, which put the entire trace containing a matching span into the index. The former is configured with a span query and a Span rate and can be searched in Span Explorer. The latter adds a Trace rate on top of that and can be used in Trace Queries in addition to Span Explorer (as of September 2026, Source: Trace Retention). A Trace rate can greatly increase the index count. In the example from the official documentation, when a trace has 100 spans on average and 5 of them match the condition, setting a Trace rate also puts the remaining 95 spans of the selected trace into the index. The Span rate is evaluated first, and the Trace rate applies only to the traces selected there. Choosing trace-level only when you need to answer questions that span an entire trace is the basic way to keep the count down.
Ingested GB and indexed span count are different yardsticks
The relationship with ingestion volume is easy to confuse. Ingestion (Ingested Spans) is counted in GB, while the index (Indexed Spans) is counted by number of spans. Reducing ingestion also reduces the candidates for the index, but reducing the index does not reduce the ingested GB. These two yardsticks also appear as separate line items in APM billing. Indexed Spans beyond the allotment are billed per million spans at a unit price set for each retention period, and the unit price differs between annual contract and on-demand (billing structure as of August 2026; Source: Datadog Pricing). This article explains how billing works. For current unit prices and plans, refer to Datadog's official pricing page. How the allotment is counted and how overage is calculated are left to the explanation of APM pricing. To check usage, go from the total in datadog.estimated_usage.apm.indexed_spans down to the breakdown by retained_by.