Top Description Methods
io.opentelemetry.context.propagation

public Interface TextMapPropagator

Known Direct Implementers
io.opentelemetry.context.propagation.MultiTextMapPropagator, io.opentelemetry.context.propagation.NoopTextMapPropagator
Annotations
@ThreadSafe
Imports
io.opentelemetry.context.Context, java.util.ArrayList, .Arrays, .Collection, .List, javax.annotation.Nullable, javax.annotation.concurrent.ThreadSafe
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 Summary

Modifier and TypeMethod and Description
public static TextMapPropagator
composite(TextMapPropagator... propagators)

Returns a TextMapPropagator which simply delegates injection and extraction to the provided propagators.

public static TextMapPropagator
composite(Iterable<TextMapPropagator> propagators)

Returns a TextMapPropagator which simply delegates injection and extraction to the provided propagators.

public <
the type of carrier of the propagation fields, such as an http request.
C> Context

Returns:

the Context containing the extracted data.
extract(Context
the Context used to store the extracted value.
context, C
holds propagation fields. For example, an outgoing message or http request.
carrier, TextMapGetter<C>
invoked for each propagation key to get data from the carrier.
getter)

Extracts data from upstream.

public Collection<String>

Returns:

the fields that will be used by this formatter.
fields()

The propagation fields defined.

public <
carrier of propagation fields, such as an http request
C> void
inject(Context
the Context containing the value to be injected.
context, C
holds propagation fields. For example, an outgoing message or http request.
carrier, TextMapSetter<C>
invoked for each propagation key to add or remove.
setter)

Injects data for downstream consumers, for example as HTTP headers.

public static TextMapPropagator
noop()

Returns a TextMapPropagator which does no injection or extraction.

Method Detail

compositeback to summary
public 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.

compositeback to summary
public 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.

extractback to summary
public <C> Context extract(Context context, 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.

Parameters
<C>
the type of carrier of the propagation fields, such as an http request.
context:Context

the Context used to store the extracted value.

carrier:C

holds propagation fields. For example, an outgoing message or http request.

getter:TextMapGetter<C>

invoked for each propagation key to get data from the carrier.

Returns:Context

the Context containing the extracted data.

fieldsback to summary
public 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:Collection<String>

the fields that will be used by this formatter.

injectback to summary
public <C> void inject(Context context, 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.

Parameters
<C>
carrier of propagation fields, such as an http request
context:Context

the Context containing the value to be injected.

carrier:C

holds propagation fields. For example, an outgoing message or http request.

setter:TextMapSetter<C>

invoked for each propagation key to add or remove.

noopback to summary
public static TextMapPropagator noop()

Returns a TextMapPropagator which does no injection or extraction.