Package io.opentelemetry.context.propagation

Interface TextMapPropagator

  • @ThreadSafe
public interface TextMapPropagator
    Injects and extracts a value as text into carriers that travel in-band across process boundaries. Encoding is expected to conform to the HTTP Header Field semantics. Values are often encoded as RPC/HTTP request headers.

    The carrier of propagated data on both the client (injector) and server (extractor) side is usually an http request. Propagation is usually implemented via library- specific request interceptors, where the client-side injects values and the server-side extracts them.

    Specific concern values (traces, correlations, etc) will be read from the specified Context, and resulting values will be stored in a new Context upon extraction. It is recommended to use a single Context.Key to store the entire concern data: 

    
 public static final Context.Key CONCERN_KEY = Context.key("my-concern-key");
 public MyConcernPropagator implements TextMapPropagator {
   public <C> void inject(Context context, C carrier, Setter<C> setter) {
     Object concern = CONCERN_KEY.get(context);
     // Use concern in the specified context to propagate data.
   }
   public <C> Context extract(Context context, C carrier, Getter<C> getter) {
     // Use getter to get the data from the carrier.
     return context.withValue(CONCERN_KEY, concern);
   }
 }

    • Method Detail

      • composite

        static TextMapPropagator composite​(TextMapPropagator... propagators)
        Returns a TextMapPropagator which simply delegates injection and extraction to the provided propagators.

        Invocation order of TextMapPropagator#inject() and TextMapPropagator#extract() for registered trace propagators is undefined.

      • composite

        static TextMapPropagator composite​(Iterable<TextMapPropagator> propagators)
        Returns a TextMapPropagator which simply delegates injection and extraction to the provided propagators.

        Invocation order of TextMapPropagator#inject() and TextMapPropagator#extract() for registered trace propagators is undefined.

      • fields

        Collection<String> fields()
        The propagation fields defined. If your carrier is reused, you should delete the fields here before calling inject(Context, Object, TextMapSetter) )}.

        For example, if the carrier is a single-use or immutable request object, you don't need to clear fields as they couldn't have been set before. If it is a mutable, retryable object, successive calls should clear these fields first.

        Some use cases for this are:

        • Allow pre-allocation of fields, especially in systems like gRPC Metadata
        • Allow a single-pass over an iterator
        Returns:
        the fields that will be used by this formatter.

      • inject

        <C> void inject​(Context context,
                @Nullable
                C carrier,
                TextMapSetter<C> setter)
        Injects data for downstream consumers, for example as HTTP headers. The carrier may be null to facilitate calling this method with a lambda for the TextMapSetter, in which case that null will be passed to the TextMapSetter implementation.
        Type Parameters:
        C - carrier of propagation fields, such as an http request
        Parameters:
        context - the Context containing the value to be injected.
        carrier - holds propagation fields. For example, an outgoing message or http request.
        setter - invoked for each propagation key to add or remove.

      • extract

        <C> Context extract​(Context context,
                    @Nullable
                    C carrier,
                    TextMapGetter<C> getter)
        Extracts data from upstream. For example, from incoming http headers. The returned Context should contain the extracted data, if any, merged with the data from the passed-in Context.

        If the incoming information could not be parsed, implementations MUST return the original Context, unaltered.

        Type Parameters:
        C - the type of carrier of the propagation fields, such as an http request.
        Parameters:
        context - the Context used to store the extracted value.
        carrier - holds propagation fields. For example, an outgoing message or http request.
        getter - invoked for each propagation key to get data from the carrier.
        Returns:
        the Context containing the extracted data.