@ExperimentalApi public abstract class TextFormat extends Object
trace identifiers
as text into carriers that travel
in-band across process boundaries. Identifiers are often encoded as messaging or RPC request
headers.
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.
Example of usage on the client:
private static final Tracer tracer = Tracing.getTracer();
private static final TextFormat textFormat = Tracing.getPropagationComponent().getTextFormat();
private static final TextFormat.Setter setter = new TextFormat.Setter<HttpURLConnection>() {
public void put(HttpURLConnection carrier, String key, String value) {
carrier.setRequestProperty(field, value);
}
}
void makeHttpRequest() {
Span span = tracer.spanBuilder("Sent.MyRequest").startSpan();
try (Scope s = tracer.withSpan(span)) {
HttpURLConnection connection =
(HttpURLConnection) new URL("http://myserver").openConnection();
textFormat.inject(span.getContext(), connection, httpURLConnectionSetter);
// Send the request, wait for response and maybe set the status if not ok.
}
span.end(); // Can set a status.
}
Example of usage on the server:
private static final Tracer tracer = Tracing.getTracer();
private static final TextFormat textFormat = Tracing.getPropagationComponent().getTextFormat();
private static final TextFormat.Getter<HttpRequest> getter = ...;
void onRequestReceived(HttpRequest request) {
SpanContext spanContext = textFormat.extract(request, getter);
Span span = tracer.spanBuilderWithRemoteParent("Recv.MyRequest", spanContext).startSpan();
try (Scope s = tracer.withSpan(span)) {
// Handle request and send response back.
}
span.end()
}
Modifier and Type | Class and Description |
---|---|
static class |
TextFormat.Getter<C>
Class that allows a
TextFormat to read propagated fields from a carrier. |
static class |
TextFormat.Setter<C>
Class that allows a
TextFormat to set propagated fields into a carrier. |
Constructor and Description |
---|
TextFormat() |
Modifier and Type | Method and Description |
---|---|
abstract <C> SpanContext |
extract(C carrier,
TextFormat.Getter<C> getter)
Extracts the span context from upstream.
|
abstract List<String> |
fields()
The propagation fields defined.
|
abstract <C> void |
inject(SpanContext spanContext,
C carrier,
TextFormat.Setter<C> setter)
Injects the span context downstream.
|
public abstract List<String> fields()
inject(SpanContext, Object, Setter)
.
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.
public abstract <C> void inject(SpanContext spanContext, C carrier, TextFormat.Setter<C> setter)
spanContext
- possibly not sampled.carrier
- holds propagation fields. For example, an outgoing message or http request.setter
- invoked for each propagation key to add or remove.public abstract <C> SpanContext extract(C carrier, TextFormat.Getter<C> getter) throws SpanContextParseException
carrier
- holds propagation fields. For example, an outgoing message or http request.getter
- invoked for each propagation key to get.SpanContextParseException
- if the input is invalid