TraceContext class

Correlation identifiers for one request, ambient for its whole lifetime.

A request id that only exists as a header dies at the first hop: a call the handler makes to another service opens a fresh, uncorrelated request, and the two services' logs cannot be joined afterwards. This carries the identifiers in the zone instead, so anything running inside the request — a logger, a repository, an outbound client — can reach them without being handed them explicitly.

final id = TraceContext.current?.requestId;

Sending them on is outboundHeaders. Nothing does that automatically: what counts as a trusted peer is the app's call, not the framework's, and forwarding correlation headers to an arbitrary third party is a small information leak.

This deliberately propagates traceparent rather than creating spans. A collector that already understands W3C Trace Context keeps working, and a service that sits between two instrumented ones stops breaking the chain — without this package taking on span lifecycles, samplers or exporters.

Constructors

TraceContext({required String requestId, String? traceparent, String? tracestate, Map<String, String>? baggage})

TraceContext.from({String? requestId, String? traceparent, String? tracestate, Map<String, String>? baggage})

Builds a context from whatever the caller sent, generating what is missing.

factory

Properties

baggage → Map<String, String>

Key/value pairs to carry alongside the identifiers — a tenant, a feature-flag cohort.

final

hashCode → int

The hash code for this object.

no setter, inherited

requestId → String

Identifies this request across every service that handles it.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

traceparent → String?

W3C Trace Context traceparent, when the caller sent one.

final

tracestate → String?

W3C Trace Context tracestate, when the caller sent one.

final

Methods

encodedBaggage() → String?

baggage in the W3C baggage header format, or null when empty.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

outboundHeaders() → Map<String, String>

The headers to attach to an outbound call so the next service joins this request rather than starting its own.

runWith<R>(R body()) → R

Runs body with this context installed as the ambient one.

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Properties

current → TraceContext?

The context for the request currently being handled, if any.

no setter

Static Methods

decodeBaggage(String? header) → Map<String, String>

Parses a W3C baggage header value.

newRequestId() → String

A fresh request id: 16 random bytes, hex encoded.

Constants

baggageHeader → const String

requestIdHeader → const String

traceparentHeader → const String

tracestateHeader → const String

zoneKey → const Symbol