Traceparent decoder & generator

What a traceparent header is

traceparent is the HTTP header the W3C Trace Context standard uses to carry a trace from one service to the next. Every OpenTelemetry SDK writes it on outgoing requests and reads it on incoming ones, which is how a span in one service becomes the child of a span in another.

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
             │  │                                │                │
             │  trace id (32 hex)                parent id (16)   flags
             version

The four fields

• version — two hex digits, 00 today. ff is forbidden.
• trace id — 16 bytes as 32 lowercase hex characters, the same for every span in the trace. All zeroes is invalid.
• parent id — 8 bytes as 16 hex characters: the span id of the span that made the call. All zeroes is invalid.
• trace flags — one byte. Bit 0 (01) is sampled: the caller may have recorded this trace. Level 2 adds bit 1 (02), random: the trace id's right-most seven bytes are random, so it can be used for consistent sampling.

Why a header gets dropped

A receiver that finds the header malformed must ignore it and start a new trace — so a bad header never errors, it silently splits one request into two traces. The usual causes are uppercase hex (the spec allows only lowercase), a trace id padded or truncated to the wrong length, an all-zero id from an uninitialised context, or a proxy that rewrites the header. The decoder above names which one it is.

Following the trace

The trace id is the key to everything the request touched. In Bilis, the same id links a log line to its span and opens the whole waterfall, across every service that passed the header on. See the docs for sending traces over OTLP.