Traces & Spans
How Incidentary models distributed request flows as causal chains of spans within a trace.
Traces & Spans
A trace is a causal chain of events across one or more services triggered by a single originating request. A span is a single unit of work within that chain.
Traces
A trace represents the complete lifecycle of a request as it propagates through your system — from the first inbound HTTP call at your edge service, through every downstream service it touches, to the final response.
Every span in a trace shares the same trace_id — a UUID minted by the SDK when the first inbound request arrives with no existing trace context.
Trace: 3f7a...
├── api-gateway HTTP_IN GET /orders/123 200 12ms
│ ├── order-service HTTP_IN GET /orders/123 200 10ms
│ │ ├── inventory-service HTTP_OUT GET /stock/item-42 200 3ms
│ │ └── pricing-service HTTP_OUT GET /price/item-42 500 8ms
│ └── auth-service HTTP_OUT POST /validate-token 200 1msSpans
A span corresponds to a single HTTP_IN or HTTP_OUT event captured by the SDK middleware.
Each span carries:
| Field | Description |
|---|---|
ce_id | Unique span identifier |
trace_id | Shared across all spans in the trace |
parent_ce_id | The ce_id of the span that triggered this one (null for root) |
kind | HTTP_IN (received request) or HTTP_OUT (outbound call) |
status | HTTP response status code |
duration_ns | Elapsed time from request start to response completion |
wall_ts_ns | Absolute wall-clock timestamp in nanoseconds |
The causal waterfall
In the Incidentary dashboard, traces render as a causal waterfall — a timeline view where each span is positioned relative to its parent, making the critical path and bottlenecks immediately visible.
Unlike a flat log stream (where events appear in emission order), the waterfall shows causal order: which call caused which downstream call, and how latency compounds across the chain.
Trace propagation
The SDK propagates trace context between services automatically via HTTP headers. No manual instrumentation is required on individual routes.
For the full propagation header specification, see Wire Format.