Full lesson
Explore the full explanation, examples, and visuals at your own pace.
Part 1
A trace is a set of spans that share one trace_id and are linked by parent IDs. A span is one unit of work. Here, hello is the root, with no parent. Its two children, hello-greetings and hello-salutations, point back to it, so together they form one tree.
hello span: the root
Start with the hello span. Its trace_id identifies the whole request, so every span in this trace will carry the same value. The span_id belongs to this span alone. And parent_id is null, meaning nothing sits above it. That's how you know hello is the root span.
{
"name": "hello",
"context": {
"trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
"span_id": "051581bf3cb55c13"
},
"parent_id": null
}hello-greetings span: a child
Look at hello-greetings. Its trace_id is identical to the root's, so it belongs to the same trace. Its parent_id, 051581bf, is hello's span_id. That match is the link. Same trace_id groups spans; parent_id draws the tree. hello-salutations links to hello the same way.
{
"name": "hello-greetings",
"context": {
"trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
"span_id": "5fb397be34d26b51"
},
"parent_id": "051581bf3cb55c13"
}The tree, drawn as a waterfall
General knowledgeTracing tools usually draw this tree as a waterfall. The indentation comes from parent_id, so hello sits on top with its two children below. Each bar's position and length come from start and end times. Here, hello-salutations runs about 139 microseconds, inside hello's roughly 486.
Inside hello-greetings: attributes and events
Inside hello-greetings, attributes are key-value metadata, like http.route set to some_route2. Events are timestamped moments within the span, here hey there and bye now. The rule is simple. If the timestamp matters, use an event. If it doesn't, use an attribute.
"attributes": {
"http.route": "some_route2"
},
"events": [
{ "name": "hey there!",
"timestamp": "2022-04-29T18:52:58.114561Z" },
{ "name": "bye now!",
"timestamp": "2022-04-29T18:52:58.114585Z" }
]Span status: three values
Every span has a status. Unset is the default, and surprisingly, it already means the operation finished without an error. Error means something failed, like an HTTP 500. Ok is a deliberate final call by a developer, and you rarely need it.
- Unset: the default, completed without error
- Error: something failed, such as HTTP 500
- Ok: explicitly marked successful by a developer
Span kind: a hint for assembly
Span kind is a hint that tells the backend how to assemble the trace. A server span's parent is often a remote client span, and a consumer's parent is a producer. Internal covers work inside one process, and it's assumed when no kind is set.
- Client to Server: synchronous remote calls
- Producer to Consumer: queued, asynchronous jobs
- Internal: work inside one process
Same trace_id groups the spans; parent_id draws the tree.
General knowledgeThe same trace_id groups the spans, and parent_id draws the tree. If a waterfall looks broken, check those two values first.
