Package org.apache.juneau.http.tracing

Interface TraceContextCarrier

public interface TraceContextCarrier
Neutral, tracer-agnostic carrier of W3C trace-context fields (traceparent / tracestate / baggage) from a source that need not be an HTTP request.

juneau-rest-server has exactly one built-in carrier source — HTTP request headers, read directly by the OpenTelemetry bridge's RestRequestTextMapGetter. This interface exists so a second carrier source — for example a JSON-RPC/MCP request's nested params._meta object — can be read/written through the exact same shape a TracerHook bridge already knows how to consume, without that bridge (or this module) depending on the concept of MCP, JSON-RPC, or any specific wire format.

A single carrier instance may also be a composite that consults more than one underlying source with a defined precedence (for example: an explicit metadata key wins, an absent key falls back to the equivalent HTTP header). This interface makes no assumption about how many underlying sources a given implementation consults — only that get(String) return the effective value for a key after any such precedence is applied.

Implementations are read/write: get(String) and keys() support inbound context extraction (a TracerHook bridge reading a remote parent out of the carrier); set(String, String) supports outbound context injection (a bridge or TraceContexts#inject(TracerHook, TraceContextCarrier) writing the current trace context into the carrier for a caller to read back).

See Also:
Since:
10.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    get(String key)
    Returns the effective value for the given key.
    Iterable<String>
    keys()
    Returns every key this carrier can resolve through get(String).
    void
    set(String key, String value)
    Writes a value for the given key.

  • Method Details

    • get

      String get(String key)
      Returns the effective value for the given key.
      Parameters:
      key - The carrier key (e.g. "traceparent", "tracestate", "baggage"). Never null.
      Returns:
      The value for key, or null if the key is absent from every underlying source the carrier consults.

    • keys

      Iterable<String> keys()
      Returns every key this carrier can resolve through get(String).

      For a composite carrier, this is the union of the keys available across every underlying source — not just the source that happens to win precedence for any single key.

      Returns:
      The carrier's keys. Never null; empty if the carrier currently has no keys.

    • set

      void set(String key, String value)
      Writes a value for the given key.

      Used for outbound context injection — a TracerHook bridge rendering the current trace context into the carrier so a caller can read it back (for example, an MCP adapter copying the rendered traceparent into a JSON-RPC result's _meta).

      Parameters:
      key - The carrier key (e.g. "traceparent", "tracestate", "baggage"). Never null.
      value - The value to write. Never null.