Interface TextMapPropagator
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 TypeMethodDescriptionstatic 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.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 Details
-
composite
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
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
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
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
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.
-