Request Tracing

A trace represents a single "request". "Request" is loosely defined, but typical examples include:

• A single HTTP request
• A cron job
• A single command (as with a CLI tool)

A trace has a unique ID, and a tree of spans...

A trace is made up of spans. You can think of a span as a stack frame in a stack trace, though the correlation is imprecise because spans can be defined arbitrarily, not only at function boundaries.

Each trace has at least one span, the "root span". Typically, a root span has one or more child spans, which in turn may have grandchild spans, to an arbitrary depth.

Each span has:

• A unique ID
• A name (e.g. "HTTP GET /login")
• A start and end time
• Optional metadata such as status, attributes, and events

Attributes

Spans may contain an arbitrary set of key/value pairs known as attributes. These are conceptually similar to the key/value pairs we send to logs in earlier chapters.

http.method=POST
http.route=/login
user.id=1234

Events

Events are timestamped annotations on a span. They indicate the instant something noteworthy happened within a span. While we won't be exploring events fully in this course, it's important to know that they exist.

Status

Finally, each span has a status. By default, each span's status is UNSET, but you can explicitly set a span's status to either OK or ERROR as well. This three-valued system allows you to indicate that specific spans (or operations) within a larger request failed, without failing the entire operation.

Trace 123
 ├── Span A: HTTP handler        (OK)
 │     ├── Span B: load user     (OK)
 │     ├── Span C: apply coupons (ERROR)
 │     └── Span D: write audit   (OK)
 └── ...