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);
   }
 }
 

Since:

0.1.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	TextMapPropagator.Getter<C> Interface that allows a TextMapPropagator to read propagated fields from a carrier.
static interface	TextMapPropagator.Setter<C> Class that allows a TextMapPropagator to set propagated fields into a carrier.

Method Summary

Modifier and Type	Method and Description
<C> io.grpc.Context	extract(io.grpc.Context context, C carrier, TextMapPropagator.Getter<C> getter) Extracts the value from upstream.
List<String>	fields() The propagation fields defined.
<C> void	inject(io.grpc.Context context, C carrier, TextMapPropagator.Setter<C> setter) Injects the value downstream, for example as HTTP headers.

Method Detail

fields

List<String> fields()

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

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.

Returns:

list of fields that will be used by this formatter.

Since:

0.1.0

inject

<C> void inject(io.grpc.Context context,
                @Nullable
                C carrier,
                TextMapPropagator.Setter<C> setter)

Injects the value downstream, for example as HTTP headers. The carrier may be null to facilitate calling this method with a lambda for the TextMapPropagator.Setter, in which case that null will be passed to the TextMapPropagator.Setter 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.

Since:

0.1.0

extract

<C> io.grpc.Context extract(io.grpc.Context context,
                            C carrier,
                            TextMapPropagator.Getter<C> getter)

Extracts the value from upstream. For example, as http headers.

If the value could not be parsed, the underlying implementation will decide to set an object representing either an empty value, an invalid value, or a valid value. Implementation must not set null.

Type Parameters:

C - carrier of 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.

Returns:

the Context containing the extracted value.

Since:

0.1.0