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 newContext
upon extraction. It is recommended to use a singleContext.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
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description static TextMapPropagator
composite(TextMapPropagator... propagators)
Returns aTextMapPropagator
which simply delegates injection and extraction to the provided propagators.static TextMapPropagator
composite(Iterable<TextMapPropagator> propagators)
Returns aTextMapPropagator
which simply delegates injection and extraction to the provided propagators.<C> Context
extract(Context context, C carrier, TextMapGetter<C> getter)
Extracts data from upstream.Collection<String>
fields()
The propagation fields defined.<C> void
inject(Context context, C carrier, TextMapSetter<C> setter)
Injects data for downstream consumers, for example as HTTP headers.static TextMapPropagator
noop()
Returns aTextMapPropagator
which does no injection or extraction.
-
-
-
Method Detail
-
composite
static TextMapPropagator composite(TextMapPropagator... propagators)
Returns aTextMapPropagator
which simply delegates injection and extraction to the provided propagators.Invocation order of
TextMapPropagator#inject()
andTextMapPropagator#extract()
for registered trace propagators is undefined.
-
composite
static TextMapPropagator composite(Iterable<TextMapPropagator> propagators)
Returns aTextMapPropagator
which simply delegates injection and extraction to the provided propagators.Invocation order of
TextMapPropagator#inject()
andTextMapPropagator#extract()
for registered trace propagators is undefined.
-
noop
static TextMapPropagator noop()
Returns aTextMapPropagator
which does no injection or extraction.
-
fields
Collection<String> fields()
The propagation fields defined. If your carrier is reused, you should delete the fields here before callinginject(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 theTextMapSetter
, in which case that null will be passed to theTextMapSetter
implementation.- Type Parameters:
C
- carrier of propagation fields, such as an http request- Parameters:
context
- theContext
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
- theContext
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.
-
-