Struct TraceCarrier 

pub struct TraceCarrier {
    pub traceparent: Option<String>,
    pub tracestate: Option<String>,
}

A W3C trace context in transit, sized to fit in a request payload.

Both fields are Option because most calls happen with no active span: no sampling, or OTLP switched off. The carrier is then two Nones that serialise to nothing. #[serde(default, skip_serializing_if = …)] makes that free on the wire. It is a payload-size optimisation for the common empty case, not a compatibility shim for older encodings. Krabka keeps no such shims: see CLAUDE.md.

This type does not derive PartialEq, and that is deliberate. RPC envelopes hold a carrier next to a request, and their equality must stay a pure function of the request payload. A derived PartialEq would silently make two identical requests compare unequal because they were traced differently.

Fields

traceparent: Option<String>

The validated, re-rendered W3C traceparent.

tracestate: Option<String>

The validated, re-rendered W3C tracestate, when the peer sent one small enough to forward.

Implementations

impl TraceCarrier

pub fn capture_current() -> Self

Capture the currently active span’s trace context.

The carrier is empty when there is no active span, when the span is not sampled, or when OTLP is disabled. It is always safe to call on a hot path.

pub fn from_w3c( traceparent: &str, tracestate: Option<&str>, ) -> Result<Self, TraceContextError>

Build a carrier from a peer-supplied traceparent and tracestate.

This function validates both inputs. traceparent must match ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$ with a non-zero trace-id and a non-zero span-id. The function drops the tracestate, and does not return an error, when it is more than 512 bytes, when it has more than 32 list members, or when it is not a well-formed list. The traceparent still applies, because a lost vendor state is better than a lost trace.

This function stores neither input verbatim. It parses both, then re-renders them from the SpanContext and the TraceState, so a hostile value cannot get into a span attribute or a log line.

Errors

Returns TraceContextError when traceparent fails validation. A caller on an ingress path should discard the error and not show it: a bad trace header must never fail the request that carried it.

pub fn from_headers<'a, I, V>(headers: I) -> Self

where I: IntoIterator<Item = (&'a str, V)>, V: AsRef<[u8]>,

Build a carrier from the headers on a Kafka record.

Each header is a key plus a raw byte value. This function does the same validation as TraceCarrier::from_w3c. But a non-UTF-8, absent, or invalid value gives an empty carrier and not an error, because a consumer that cannot read the producer’s trace context must still apply the record.

pub fn is_empty(&self) -> bool

true when there is no trace context to propagate.

pub fn apply_to(&self, span: &Span)

Make span a child of the carried context.

Work on this side of the boundary then joins the caller’s trace. This method does nothing when the carrier is empty.

pub fn link_into(&self, span: &Span)

Attach the carried context to span as an OpenTelemetry link.

The carried context becomes a link, not the parent of span. This method does nothing when the carrier is empty.

A link is the correct relation when many nodes do the linked work, or when the work runs long after the operation that started it. Every follower applies a WAL record, and recovery replays that record hours after the commit. A parent relation would stretch one trace across the retention period, and would force export of every apply of every sampled write.

pub fn span_context(&self) -> Option<SpanContext>

The remote SpanContext this carrier describes.

None when the carrier is empty, or when it holds a value that does not parse.

pub fn headers(&self) -> impl Iterator<Item = (&str, &[u8])> + '_

The carrier as (key, value) header pairs for a Kafka record.

The iterator yields nothing when the carrier is empty.

Trait Implementations

impl Clone for TraceCarrier

fn clone(&self) -> TraceCarrier

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TraceCarrier

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TraceCarrier

fn default() -> TraceCarrier

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for TraceCarrier

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for TraceCarrier

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.