Package brave.propagation

Interface Propagation<K>

Type Parameters:

K - Deprecated except when a String.

All Known Implementing Classes:

B3Propagation, BaggagePropagation, ExtraFieldPropagation

public interface Propagation<K>

Injects and extracts trace identifiers as text into requests that travel in-band across process boundaries. Identifiers are often encoded as messaging or RPC request headers.

Propagation example: HTTP

When using HTTP, the client (injector) and server (extractor) use request headers. The client injects the trace context into headers before the request is sent to the server. The server extracts a trace context from these headers before processing the request.

Since:

4.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Propagation.Factory
static interface	Propagation.Getter<R,K>	Gets the first value of the given propagation key or returns null.
static interface	Propagation.KeyFactory<K>	Deprecated. since 5.12 non-string keys are no longer supported
static interface	Propagation.RemoteGetter<R>	Used as an input to extractor(Getter) extract the trace context and any baggage from propagated fields.
static interface	Propagation.RemoteSetter<R>	Used as an input to injector(Setter) inject the trace context and any baggage as propagated fields.
static interface	Propagation.Setter<R,K>	Replaces a propagated key with the given value.

Field Summary

Fields

Modifier and Type	Field	Description
static Propagation<String>	B3_SINGLE_STRING	Deprecated. Since 5.9, use B3Propagation.newFactoryBuilder() to control inject formats.
static Propagation<String>	B3_STRING	Defaults B3 formats based on Request type.

Method Summary

Modifier and Type	Method	Description
<R> TraceContext.Extractor<R>	extractor(Propagation.Getter<R,K> getter)
<R> TraceContext.Injector<R>	injector(Propagation.Setter<R,K> setter)	Replaces a propagated field with the given value.
List<K>	keys()	The propagation fields defined.

Field Details

B3_STRING

static final Propagation<String> B3_STRING

Defaults B3 formats based on Request type. When not a Request (e.g. in-process messaging), this uses B3Propagation.Format.SINGLE_NO_PARENT.

Since:

4.0

B3_SINGLE_STRING

@Deprecated static final Propagation<String> B3_SINGLE_STRING

Deprecated.

Since 5.9, use B3Propagation.newFactoryBuilder() to control inject formats.

Method Details

keys

List<K> keys()

The propagation fields defined. If your request is reused, you should delete the fields here before calling Propagation.Setter.put(Object, Object, String).

For example, if the request 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.

Note: Depending on the format, keys returned may not all be mandatory.

Note: If your implementation carries baggage, such as correlation IDs, do not return the names of those fields here. If you do, they will be deleted, which can interfere with user headers.

Since:

4.0

See Also:

BaggagePropagation.allKeyNames(Propagation)

injector

<R> TraceContext.Injector<R> injector(Propagation.Setter<R,K> setter)

Replaces a propagated field with the given value. Saved as a constant to avoid runtime allocations. For example, a setter for an HttpURLConnection would be the method reference URLConnection.addRequestProperty(String, String)

Type Parameters:

R - Usually, but not always, an instance of Request.

Parameters:

setter - invoked for each propagation key to add.

Since:

4.0

See Also:

Propagation.RemoteSetter

extractor

<R> TraceContext.Extractor<R> extractor(Propagation.Getter<R,K> getter)

Type Parameters:

R - Usually, but not always, an instance of Request.

Parameters:

getter - invoked for each propagation key to get.

Since:

4.0

See Also:

Propagation.RemoteGetter