Span

Overview

A span is a record of one piece of work performed in a distributed system, captured as a unit with a duration. Datadog's official glossary describes a span as a logical unit of work over a period of time, and the official APM terminology page states that a trace is made up of one or more spans. Once you grasp this relationship, you can see where the resolution of a performance investigation is decided. Looking at a trace alone tells you only "how many seconds this request took", not the breakdown. Was the database query slow, were you waiting on an external service's response, or is your own code using the time? What makes this separation possible is the nested structure of spans. This entry walks through what a span records, how parent-child relationships are formed, and which of the spans you send can be searched later.

A unit with the start and end of one piece of work

Datadog's official glossary describes a span as a logical unit of work over a period of time in a distributed system. In other words, a span is an interval, not a point. Where a log is a point record saying "this event happened at this time", a span has width: "this work started here and ended here". This difference is why spans become necessary when the conversation turns to performance. Each span has a name. The official APM terminology page gives the example of grouping dynamic web endpoints under a static span name of web.request, and of using the span name db.query for database queries. Names are kept static because if you used an endlessly varying string such as a URL directly as the name, you could no longer aggregate. For an aggregation axis there is a separate concept called a resource, and the official page explains that typical resources are an instrumented web endpoint, a database query, or a background job. In monitoring without the span as a unit, the work of confirming the cause of slowness starts from guesswork. A metric tells you the response time graph spiked, and a log tells you an error occurred, but neither lets you read how much of that one request's 2 seconds went to what. The result is a detour: you guess "it is probably the database", add logging, and wait for a recurrence. With spans, you just open that one request and look at the breakdown. The difference is that the first step of the investigation starts from observation instead of a guess.

Reading the nesting - the parent-child structure within one request

Spans are recorded not as a flat list but as a parent-child nesting. The official APM terminology page calls the span at the entrance of a trace the entry-point span and explains that its span name ties the service to the endpoint. The mechanism for crossing services is also spelled out: identifiers such as the trace ID and parent span ID are injected into HTTP headers and propagated, so that spans born in separate services are stitched together into one distributed trace.

With this shape, you can read the time breakdown by subtraction. Subtract the lengths of the child spans from the length of the entry span, and what remains is the time the service itself used. If you learn that "of the 2 seconds total, 1.7 seconds were spent waiting on an external service, and my own code used only 0.3 seconds", then the thing to fix is not the code. That subtraction holds as-is only when the children execute sequentially, however. In a setup where child operations run concurrently, the sum of the children's lengths can exceed the parent's length. When looking at the nested view, it is more reliable not to assume you can add vertically, and instead to look at where each span sits on the time axis. The trace view is displayed in a waterfall shape precisely so you can read these positions.

The spans you send and the spans you can search later are decided separately

The understanding that more spans make investigation easier has one gap. Not every span you send stays searchable forever. As of August 2026, the official APM terminology page explains two mechanisms side by side. One is ingestion control: you send up to 100% of traces to Datadog, and they are available for live search and analytics for 15 minutes. The other is retention filters, described as a control you configure in the Datadog UI with tag-based conditions to decide which spans are indexed for 15 days. The official glossary treats these retention filters as a mechanism synonymous with indexing. Translated into operations, this becomes the following difference in time. Right in the middle of an incident, you can search the spans you are sending almost as they are. But when you search with the same conditions the next day, only the spans that were targeted for indexing come back. This is the reality behind the experience of "I could see it yesterday but it is gone today"; the data is not corrupted and no setting has disappeared. It therefore fits reality better to think of retention filters as investigation design rather than as a cost setting. What you need to decide is "what kind of span might I want to look back on a week from now?" Ones containing errors, ones slower than a threshold, ones for endpoints that carry business weight such as payments. Conversely, even if you keep every one of the large volume of spans that are healthy and fast, you will almost never have occasion to revisit them. The billing structure is also two-tiered. Ingested spans are counted by data volume, and indexed spans are counted by number. The amounts themselves can be checked on the Datadog pricing page, and the retention mechanism is covered on the Retention and Log Index pages. The takeaway is that the same idea that splits log ingestion and indexing into two tiers applies to spans as well.

Finer does not necessarily mean clearer

Once you start instrumenting, you inevitably run into the question of how finely to create spans. This is an area where the official documentation has no answer, so you need to hold your own criteria for judgment. The failure on the too-fine side shows up in an obvious form. If you create a span for every iteration of a loop, the span count for one request can reach into the thousands. Not only does the ingested volume grow, the waterfall stretches vertically until nothing can be read from it. If you put unbounded values such as order numbers or session IDs into the tags on a span, the cardinality problem is carried straight in, and they become unusable as an aggregation axis. The failure on the too-coarse side is quiet. If you create only one span for the whole service, the screen shows just "800 milliseconds in the app". The number is correct, yet the next action does not follow from it. When investigation time does not shrink in proportion to the satisfaction of having added instrumentation, this is the state you are in. A criterion that is easy to apply is the question "if I cut a span at this boundary, does the conclusion of the triage change?" Separating database calls from external service calls changes what you fix. Separating three lines inside the same function does not. Placing spans at boundaries that do not change the conclusion is work that only adds cost and clutter. There are also cases where granularity affects what falls within the billing scope. According to the pricing page as of August 2026, in LLM Observability the billable spans are the LLM spans that call a model, while tool, workflow, and retrieval spans are excluded. It is an example of how things called by the same word, span, are counted differently depending on their type, meaning that creating spans finely does not necessarily make things more expensive. If you first identify the boundaries that change the conclusion and then check volume and billing, in that order, you avoid the work of ripping instrumentation out later.

Keeping apart the words that share a screen

Because nearby words appear together on the APM screens, if you memorize them blurred together you will hesitate when you touch a setting. Let us separate them. The relationship between a trace and a span is containment. The official APM terminology page states that a trace tracks the time spent by an application processing a request and its outcome, and that each trace is made up of one or more spans. The whole picture of one request is the trace; one piece of work inside it is a span. Span versus resource is the difference between a record and an aggregation axis. A span is the measured value of one execution, while a resource, per the official page's explanation, refers to a unit such as an instrumented web endpoint, a database query, or a background job. You gather the many spans for the same resource and read them as throughput, latency, and error rate. The division of labor is: look at one case with a span, look at a trend with a resource. Retention filters and retention are also different things. The former is a rule that selects which spans get indexed; the latter is the value that represents the period itself for which they are kept. When you want to lower cost, you touch the former; what decides the range you can investigate is both. The difference between a span and a log goes back to the opening point: interval versus point. The two are not mutually exclusive; in Datadog they are designed so you can move back and forth between them through tags and the trace ID. Being able to pinpoint the slow interval with a span and then read the logs emitted during that interval, in that order, is the advantage of putting APM and log management on the same platform. The primary sources are Datadog's official documentation, Glossary and APM Terms and Concepts. Its positioning as a product can be checked on the APM page.