Package io.opencensus.trace.propagation
Class TextFormat
- java.lang.Object
-
- io.opencensus.trace.propagation.TextFormat
-
- Direct Known Subclasses:
B3Format
,CloudTraceFormat
,TextFormat.NoopTextFormat
,TraceContextFormat
@ExperimentalApi public abstract class TextFormat extends java.lang.Object
Injects and extractstrace 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() }
- Since:
- 0.11
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
TextFormat.Getter<C>
Class that allows aTextFormat
to read propagated fields from a carrier.private static class
TextFormat.NoopTextFormat
static class
TextFormat.Setter<C>
Class that allows aTextFormat
to set propagated fields into a carrier.
-
Field Summary
Fields Modifier and Type Field Description private static TextFormat.NoopTextFormat
NOOP_TEXT_FORMAT
-
Constructor Summary
Constructors Constructor Description TextFormat()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract <C> SpanContext
extract(C carrier, TextFormat.Getter<C> getter)
Extracts the span context from upstream.abstract java.util.List<java.lang.String>
fields()
The propagation fields defined.(package private) static TextFormat
getNoopTextFormat()
Returns the no-op implementation of theTextFormat
.abstract <C> void
inject(SpanContext spanContext, C carrier, TextFormat.Setter<C> setter)
Injects the span context downstream.
-
-
-
Field Detail
-
NOOP_TEXT_FORMAT
private static final TextFormat.NoopTextFormat NOOP_TEXT_FORMAT
-
-
Method Detail
-
fields
public abstract java.util.List<java.lang.String> fields()
The propagation fields defined. If your carrier is reused, you should delete the fields here before callinginject(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.
- Since:
- 0.11
-
inject
public abstract <C> void inject(SpanContext spanContext, C carrier, TextFormat.Setter<C> setter)
Injects the span context downstream. For example, as http headers.- Parameters:
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.- Since:
- 0.11
-
extract
public abstract <C> SpanContext extract(C carrier, TextFormat.Getter<C> getter) throws SpanContextParseException
Extracts the span context from upstream. For example, as http headers.- Parameters:
carrier
- holds propagation fields. For example, an outgoing message or http request.getter
- invoked for each propagation key to get.- Throws:
SpanContextParseException
- if the input is invalid- Since:
- 0.11
-
getNoopTextFormat
static TextFormat getNoopTextFormat()
Returns the no-op implementation of theTextFormat
.- Returns:
- the no-op implementation of the
TextFormat
.
-
-