What is a span?
A span is one timed operation within a distributed trace, such as an incoming HTTP request, a database query or a call to another service. Each span has a name, a start and end time, the trace ID, its own span ID, its parent's ID, attributes such as http.route, and a status. Spans nest to form the trace tree.
Why a span matters
Spans are what you read when investigating latency: which operation took the time, what it was called with, and whether it failed. The parent and child links show what waited on what.
Good span names and attributes make traces searchable. A span named after the route template (GET /orders/{id}) groups well; one named after the raw URL creates thousands of unique names.
How to measure a span
duration = end time − start time self time = duration − time covered by child spans
Worked example
A GET /orders/{id} span lasts 250 ms. It has two child spans that run one after the other: a database query of 80 ms and an HTTP call to the pricing service of 120 ms.
- Time in children = 80 + 120 = 200 ms.
- Self time = 250 − 200 = 50 ms spent in the handler's own code.
- If the two children ran in parallel, starting together, they would cover only 120 ms, so self time would be 130 ms.
Result: Self time is computed from the time the children cover, not from the sum of their durations, which is why a timeline view matters.
Common mistakes
- High-cardinality span names. Put IDs in attributes, not in the name.
- Not recording errors. Set the span status to error and record the exception, or failed operations look successful.
- Spans that never end. A span that is never ended is never exported. Use context managers or finally blocks.
- Sensitive data in attributes. SQL parameters, tokens and personal data do not belong in attributes. Redact them.
How Vigil handles a span
- Vigil's trace page shows every span of a stored trace on a timeline with its attributes (from a safe whitelist), and marks N+1 queries, slow queries and chatty requests.
- Spans come from Vigil's Python and Node SDKs or from any OpenTelemetry SDK, and PII redaction rules can scrub trace data at ingest.
- Slow queries and slow outbound calls are aggregated from spans across all traces and ranked by total time.
Span: frequently asked questions
What is the difference between a span and a trace?
A trace is the whole journey of one request; a span is one operation in it. A trace is the tree of spans that share one trace ID.
What is a root span?
The first span in a trace, with no parent, usually the incoming request at the edge of your system. Its duration is the request's total time.
What are span events and links?
Events are timestamped notes inside a span, such as an exception. Links connect a span to spans in other traces, for example a batch job processing messages from many requests.