← Back to concept explainers

Concept Fable

Span

Conclusion first:A span is a specific operation record within a trace. It usually represents a model call, retrieval, tool call, database query, parsing, approval, or intermediate step, and includes start time, end time, duration, inputs and outputs, status, errors, and associated context. Multiple spans combine to form a complete trace.

Span · Observability artifact

Read the story first. There is no rush to give a definition here; let the question grow on its own first.

Fable

That overlooked small seal on the long strip of paper

After Seagull Post Office began leaving a complete path for every parcel, the postmaster could finally see the whole process from counter to recipient's hands. Everyone thought the problem was solved. As long as the long strip of paper was still there, parcels would no longer disappear for no reason.

But a new problem emerged. Many packages hadn't gone missing—they were just slow. The long strips of paper showed they had completed the entire journey, but didn't indicate which segment had slowed things down. The postmaster looked at a string of stamps and could only say: this trip took two and a half days. As for whether the delay was in weighing, sorting, loading, or transfer, it was still unclear.

The old postman reminded him: you now have a route, but you still have no way to measure each segment. The long strip of paper tells you where the parcel went; only each stamp tells you what actually happened at that step.

So the post office changed its stamps. In the past one stamp only said "processed"; now every stamp had to record four things: start time, end time, handler, and result. If this step called another repository, checked another account, or waited for another cart, that also had to be written next to the stamp.

The first time the new stamp was used, problems surfaced immediately. A crate of porcelain took only a quarter-hour from counter to warehouse, but waited five two-hour periods from warehouse to dock. Looking at the stamp at the dock, the reason wasn't a slow ship but a persistent queue at packaging review. The small matter of packaging review had been hidden inside the three words "already processed."

Another time, a parcel showed fast sorting, but next to the sorting stamp was written "retried three times." Only then did the postmaster know that the sorter had actually checked the destination incorrectly three times in a row, and only got it right on the last attempt, so the result looked successful. Without this fine stamp, success would conceal instability in the process.

Gradually, the post office began to treat each stamp as the smallest unit of analysis. The entire path was called a journey, and each stamp was called a leg. To optimize the journey, you cannot stare only at the endpoint; you must first know which leg is slow, which leg is wrong, and which leg has the most retries.

Later the director said, the long strip of paper lets us see a package's whole life, and the small stamp lets us see its every breath. Without the long strip, we do not know the whole; without the small stamp, we do not know the details.

Reveal

This story is about: span

A span is a specific operation record within a trace. It usually represents a model call, retrieval, tool call, database query, parsing, approval, or intermediate step, and includes start time, end time, duration, inputs and outputs, status, errors, and associated context. Multiple spans combine to form a complete trace.

What matters is that it is not just a term, but a structural problem that repeatedly appears in real AI / Agent systems. Understanding it lets you judge when to add a model, when to change a process, and when to add governance.

Metaphor mapping

  • Long strip of paper: Trace, one end-to-end execution path
  • Each stamp: a Span, a single operation in the execution path
  • Only writing "processed": lacking fine-grained span information, making it impossible to analyze latency and errors
  • Start time and end time: the time boundaries of a span, used to calculate latency
  • Handling people and results: the execution components, state, and output of a span
  • Packaging review queue: a sub-step causes overall delay
  • Three retries but eventual success: spans can reveal the unstable process behind eventual success
  • Smallest unit of analysis: a span is the basic granularity for investigating the details of an Agent task

Andy Ren Xu's judgment

The practical value of this concept is that it helps you break "AI features that look smart" into deliverable, verifiable, and governable units of work.

traceOpenTelemetrylatencyinstrumentationobservability
京ICP备2026014272号