W3C Trace Context Level 2 propagator (W3C 20-http_request_header_format.md §Traceparent Header L51-L244; OTel context/api-propagators.md §TextMap L114-L203).

Injects and extracts the traceparent and tracestate HTTP headers. Wire format per W3C §Header Field Values L75-L96 (ABNF):

value          = version "-" version-format
version        = 2HEXDIGLC    ; "00" for this spec; "ff" invalid
version-format = trace-id "-" parent-id "-" trace-flags
trace-id       = 32HEXDIGLC   ; 16 bytes; all-zeros forbidden
parent-id      = 16HEXDIGLC   ; 8 bytes; all-zeros forbidden
trace-flags    = 2HEXDIGLC    ; 8 bit flags

Example header value:

00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

Design notes

Two places where we diverge from opentelemetry-erlang's otel_propagator_trace_context.erl to follow spec more strictly.

1. Lowercase-hex enforcement

W3C §trace-id L111 "If the trace-id value is invalid (for example if it contains non-allowed characters or all zeros), vendors MUST ignore the traceparent" and §parent-id L117 "Vendors MUST ignore the traceparent when the parent-id is invalid (for example, if it contains non-lowercase hex characters)".

We call lowercase_hex?/1 on every hex segment (version, trace-id, parent-id, trace-flags) to enforce 2HEXDIGLC. Erlang's binary_to_integer/2 accepts both cases, so its decoder silently lets uppercase hex through — we diverge to meet the spec MUST.

2. Flag byte preservation

W3C §Other Flags L202 "Vendors MUST set those to zero" applies to outgoing traffic only. On incoming, preserving the whole byte keeps us forward-compatible with future flag bits (e.g. the random-trace-id bit already defined in Level 2). Erlang rejects anything other than "00"/"01" (error(badarg)); we accept the full 0..255 range and store the byte verbatim.

3. Participating propagator, not pass-through service

W3C §Versioning L232 advises "Pass-through services should not analyze the version. They should expect that headers may have larger size limits in the future and only disallow prohibitively large headers."

This guidance targets pass-through services — intermediaries that forward the traceparent header without parsing it (proxies, gateways, load balancers).

This module is a participating propagator: we decode the header into a SpanContext, use it as the parent of new spans, and re-emit our own traceparent outbound. The participating-role MUSTs at W3C §Versioning L233-L244 apply to us, and decode_traceparent/1 satisfies each:

• L233 unparseable version prefix → restart trace. Pattern-match failure bubbles a MatchError to extract/3's catch, which returns the original context (= fresh trace start).
• L235 higher-version header shorter than 55 chars → restart. The binary pattern requires at least 55 bytes (clause 1) or a 55-byte core plus dash plus suffix (clause 2); anything shorter fails to match.
• L236-L238 hex / dash shape checks for trace-id (32 hex + dash), parent-id (16 hex + dash), and flags (2 chars at end or followed by dash) — enforced by the binary pattern itself and lowercase_hex?/1.
• L243 "MUST NOT parse or assume anything about unknown fields" — clause 2 captures the trailing bytes as _rest and discards them.
• L244 "MUST use these fields to construct the new traceparent field according to the highest version of the specification known to the implementation" — encode_traceparent/1 emits "00-...", the highest version this module implements.

The L232 hint about "prohibitively large headers" is a pass-through concern, not a MUST, and does not apply to our role. HTTP-layer size limits (Cowboy, Plug, etc.) govern the upper bound in practice.

Public API

References

• W3C Trace Context Level 2 §Traceparent Header: w3c-trace-context/spec/20-http_request_header_format.md L51-L244
• W3C Trace Context Level 2 §Versioning: same file L227-L244
• OTel Context §TextMap Propagator: opentelemetry-specification/specification/context/api-propagators.md L114-L203
• Reference impl: opentelemetry-erlang/apps/opentelemetry_api/src/otel_propagator_trace_context.erl