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()	Returns the key names used for propagation of the current span.

Field Detail

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 Detail

keys

List<K> keys()

Returns the key names used for propagation of the current span. The result can be cached in the same scope as the propagation instance.

This method exists to support remote propagation of trace IDs:

• To generate constants for all key names. ex. gRPC Metadata.Key
• To iterate fields when missing a get field by name function. ex. OpenTracing TextMap
• Detection of if a context is likely to be present in a request object
• To clear trace ID fields on re-usable requests. ex. JMS message

Notes

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

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. Instead, use BaggagePropagation which returns those names in BaggagePropagation.allKeyNames(Propagation).

Edge-cases

When a request is a single-use or immutable request object, there are no known edge cases to consider. Mutable, retryable objects such as messaging headers should be careful about some edge cases:

When multiple headers are used for trace identifiers, ex B3Propagation.Format.MULTI, producers should be careful to clear fields here before calling TraceContext.Injector.inject(TraceContext, Object) when the input is a new root span. Otherwise, a stale TraceContext.parentIdString() could be left in the headers and be mistaken for a missing root span.

Headers here should be cleared when invoking listeners in scope. Doing so prevents precedence rules that prefer the trace context in message headers from overriding the current span. Doing so would place any follow-up activity in the wrong spot in the trace tree.

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