Interface Propagation<K>
-
- Type Parameters:
K
- Deprecated except when aString
.
- All Known Implementing Classes:
B3Propagation
,BaggagePropagation
,ExtraFieldPropagation
public interface Propagation<K>
Injects and extractstrace 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 returnsnull
.static interface
Propagation.KeyFactory<K>
Deprecated.since 5.12 non-string keys are no longer supportedstatic interface
Propagation.RemoteGetter<R>
Used as an input toextractor(Getter)
extract the trace context and any baggage from propagated fields.static interface
Propagation.RemoteSetter<R>
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, useB3Propagation.newFactoryBuilder()
to control inject formats.static Propagation<String>
B3_STRING
Defaults B3 formats based onRequest
type.
-
Method Summary
All Methods Instance Methods Abstract Methods 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 onRequest
type. When not aRequest
(e.g. in-process messaging), this usesB3Propagation.Format.SINGLE_NO_PARENT
.- Since:
- 4.0
-
B3_SINGLE_STRING
@Deprecated static final Propagation<String> B3_SINGLE_STRING
Deprecated.Since 5.9, useB3Propagation.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 inBaggagePropagation.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 callingTraceContext.Injector.inject(TraceContext, Object)
when the input is a new root span. Otherwise, a staleTraceContext.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 anHttpURLConnection
would be the method referenceURLConnection.addRequestProperty(String, String)
- Type Parameters:
R
- Usually, but not always, an instance ofRequest
.- 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 ofRequest
.- Parameters:
getter
- invoked for each propagation key to get.- Since:
- 4.0
- See Also:
Propagation.RemoteGetter
-
-