Span Status and Exceptions

In this lesson we’ll explain span status: what it is, why it matters, and how exceptions affect it in distributed tracing (OpenTelemetry). What is span status? A span status indicates the result or outcome of a traced operation. When you run multiple services, they can emit hundreds or thousands of spans per minute. At scale, span status helps you quickly answer questions such as: Did an operation succeed? Are errors concentrated in a single service or spread across many?

The image explains the concept of "Span Status," indicating the result of an operation tracked by a span, with a graphic of an upward trend on a monitor. It poses the question of whether the operation succeeded, failed, or was unspecified.

Why status matters

It highlights the success or failure of individual spans within a trace.
It enables error detection and filtering in observability platforms (for example: show all spans with status = ERROR between 09:00–10:00).
It supports root-cause diagnostics across distributed systems by indicating which service, application, or environment is experiencing problems.

Span status values Span status is represented by one of three values:

UNSET (default)
ERROR
OK

The image shows a Venn diagram with three intersecting circles labeled "UNSET (default)", "ERROR", and "OK", each containing a number (01, 02, 03). It represents the three possible status values of a span.

Use this summary table to choose the right status:

Status	When to use	Notes
`UNSET`	Default for most spans; nothing noteworthy from an error perspective	Implies implicit success — common and usually preferred
`ERROR`	When an exception, timeout, or HTTP 4xx/5xx is observed	Instrumentation or application code can set this to surface failures
`OK`	When you explicitly want to mark a span as successful	Useful to override the default when handled errors should not be considered failures

How exceptions set status Tracing instrumentation commonly creates exception events on spans and sets the span status to ERROR. A typical span payload with an exception event and an ERROR status looks like:

{
  "status": {
    "status_code": "ERROR",
    "description": "404 Client Error: NOT FOUND for url: http://httpbin.org/delay"
  },
  "events": [
    {
      "name": "exception",
      "timestamp": "2025-05-01T12:58:08.969805Z",
      "attributes": {
        "exception.type": "HTTPError",
        "exception.message": "404 Not Found",
        "exception.stacktrace": "raise_for_status() -> HTTPError",
        "exception.escaped": "False"
      }
    }
  ]
}

The attributes exception.type, exception.message, and exception.stacktrace follow the OpenTelemetry semantic conventions for exceptions. These attributes let observability tools display error details and group similar errors. See the OpenTelemetry spec for exceptions for more details: https://opentelemetry.io/docs/reference/specification/semantic_conventions/exceptions/

When a span contains an exception event like the example above, the tracing SDK or instrumentation typically sets status to ERROR and includes a summary description. This makes it straightforward to filter traces for failures and inspect the associated exception attributes. When to use OK versus leaving status UNSET

Keep UNSET when nothing noteworthy has occurred (the implicit success path). This is the common default.
Use OK when you intentionally want to mark a span as successful despite non-standard conditions. Examples:
- Your application handles certain errors internally (e.g., a cache miss producing an HTTP 404 that is expected) and you do not want these spans to appear as failures.
- A span represents a step in a multi-step or asynchronous process where success is only known later; set OK explicitly when the overall operation completes successfully.

The image is a table detailing use cases and reasons for using "OK" instead of "Unset" in certain coding contexts. It lists scenarios like handling internal errors, overriding default behavior, and signaling completeness in asynchronous operations.

Recap

Span events (especially exception events) carry attributes such as exception.type, exception.message, and exception.stacktrace.
Span status offers an at-a-glance indication of success (OK), failure (ERROR), or implicit/unspecified success (UNSET).
Most spans remain UNSET. Use ERROR for detected failures and set OK explicitly only when you need to override default behavior.

Watch Video

Span Links

Span Timings