Package brave.propagation

Interface Propagation<K>

Type Parameters:

K - Usually, but not always a String

All Known Implementing Classes:

B3Propagation, ExtraFieldPropagation

public interface Propagation<K>

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

Propagation example: Http

When using http, 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 span identifiers and the server-side extracts them.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Propagation.Factory
static interface	Propagation.Getter<C,K>	Gets the first value of the given propagation key or returns null
static interface	Propagation.KeyFactory<K>	Creates keys for use in propagated contexts
static interface	Propagation.Setter<C,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

Method Summary

Modifier and Type	Method	Description
<C> TraceContext.Extractor<C>	extractor(Propagation.Getter<C,K> getter)
<C> TraceContext.Injector<C>	injector(Propagation.Setter<C,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

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 carrier is reused, you should delete the fields here before calling Propagation.Setter.put(Object, Object, String).

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.

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

Note: If your implementation carries "extra fields", 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.

injector

<C> TraceContext.Injector<C> injector(Propagation.Setter<C,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)

Parameters:

setter - invoked for each propagation key to add.

extractor

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

Parameters:

getter - invoked for each propagation key to get.