Propagators API consists of two main formats:
BinaryFormatis used to serialize and deserialize a value into a binary representation.
TextMapFormatis used to inject and extract a value as text into injectors and extractors that travel in-band across process boundaries.
Deserializing must set
is_remote to true on the returned
BinaryFormat is a formatter to serialize and deserialize a value
into a binary format.
BinaryFormat MUST expose the APIs that serializes values into bytes,
and deserializes values from bytes.
Serializes the given value into the on-the-wire representation.
- the value to serialize, can be
Returns the on-the-wire byte representation of the value.
Creates a value from the given on-the-wire encoded representation.
If the value could not be parsed, the underlying implementation SHOULD decide to return ether an empty value, an invalid value, or a valid value.
- on-the-wire byte representation of the value.
Returns a value deserialized from bytes.
TextMapFormat is a formatter that injects and extracts a value
as text into injectors and extractors 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 a http request. Propagation is usually implemented via library-specific request interceptors, where the client-side injects values and the server-side extracts them.
TextMapFormat MUST expose the APIs that injects values into injectors,
and extracts values from extractors.
The propagation fields defined. If your injector is reused, you should
delete the fields here before calling
For example, if the injector 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.
The use cases of this are:
- allow pre-allocation of fields, especially in systems like gRPC Metadata
- allow a single-pass over an iterator
Returns list of fields that will be used by this formatter.
Injects the value downstream. For example, as http headers.
SpanContextto be injected.
- the injector that holds propagation fields. For example, an outgoing message or http request.
Setterinvoked for each propagation key to add or remove.
Setter is an argument in
Inject that puts value into given field.
Setter allows a
TextMapFormat to set propagated fields into a
Setter MUST be stateless and allowed to be saved as a constant to
avoid runtime allocations. One of the ways to implement it is
Put method as described below.
Replaces a propagated field with the given value.
- the injector holds propagation fields. For example, an outgoing message or http request.
- the key of the field.
- the value of the field.
The implementation SHOULD preserve casing (e.g. it should not transform
content-type) if the used protocol is case insensitive,
otherwise it MUST preserve casing.
Extracts the value from upstream. For example, as http headers.
If the value could not be parsed, the underlying implementation will decide to return an object representing either an empty value, an invalid value, or a valid value.
- the extractor holds propagation fields. For example, an outgoing message or http request.
- the instance of
Getterinvoked for each propagation key to get.
Returns the non-null extracted value.
Getter is an argument in
Extract that get value from given field
Getter allows a
TextMapFormat to read propagated fields from a
Getter MUST be stateless and allowed to be saved as a constant to avoid
runtime allocations. One of the ways to implement it is
Get method as described below.
The Get function MUST return the first value of the given propagation
key or return
None if the key doesn’t exist.
- the extractor of propagation fields, such as an HTTP request.
- the key of the field.
get function is responsible for handling case sensitivity. If
the getter is intended to work with an HTTP request object, the getter
MUST be case insensitive. To improve compatibility with other text-based
protocols, text format implementations MUST ensure to always use the
canonical casing for their attributes. NOTE: Canonical casing for HTTP
headers is usually title case (e.g.
Content-Type instead of
The Keys function returns a vector of the propagation keys.
pub use text_map_propagator::TextMapPropagator;
- Text Propagator
- Extractor provides an interface for removing fields from an underlying struct like
- Injector provides an interface for adding fields from an underlying struct like