ForgeOpsTracker.TraceParent (forge_ops_tracker v0.13.0)

Copy Markdown View Source

Reads and writes the W3C Trace Context traceparent header (https://www.w3.org/TR/trace-context/), the vendor-neutral format for carrying one trace across service boundaries: 00-<32 hex trace-id>-<16 hex parent-id>-<2 hex flags>. Used in both directions: ForgeOpsTracker.Integrations.Phoenix parses an incoming one so the request continues the caller's trace instead of starting its own, and ForgeOpsTracker.http_span/4 builds an outgoing one so the next service along continues this request's. Ported from gems/forge_ops_tracker's trace_parent.rb.

Deliberately strict on the way in, the same posture the spec asks receivers to take: a malformed value, uppercase hex, the reserved version "ff", or an all-zero trace/parent id are all treated as "no usable header at all" (parse/1 returns nil and the request starts a fresh trace). A version this client doesn't know yet is still accepted as long as its first four fields have version 00's shape, which is what the spec says a version-00 parser should do with a future version; version 00 itself must have exactly four fields.

Summary

Functions

build(trace_id, span_id)

Builds an outgoing header value naming span_id as the parent.

generate_span_id()

16 lowercase hex characters, the W3C parent-id (span id) format; never all zeros.

generate_trace_id()

32 lowercase hex characters, the W3C trace-id format; never all zeros.

header()

The header's name, lowercase as HTTP/2 and Plug both want it.

parse(value)

%{trace_id: ..., parent_span_id: ...} for a usable header value, nil for anything else (absent, blank, malformed, or one of the explicitly invalid values above).

Functions

build(trace_id, span_id)

@spec build(String.t(), String.t()) :: String.t()

Builds an outgoing header value naming span_id as the parent.

generate_span_id()

@spec generate_span_id() :: String.t()

16 lowercase hex characters, the W3C parent-id (span id) format; never all zeros.

generate_trace_id()

@spec generate_trace_id() :: String.t()

32 lowercase hex characters, the W3C trace-id format; never all zeros.

header()

@spec header() :: String.t()

The header's name, lowercase as HTTP/2 and Plug both want it.

parse(value)

@spec parse(term()) :: %{trace_id: String.t(), parent_span_id: String.t()} | nil

%{trace_id: ..., parent_span_id: ...} for a usable header value, nil for anything else (absent, blank, malformed, or one of the explicitly invalid values above).