Package io.opencensus.tags.propagation
Class TagContextTextFormat
- java.lang.Object
-
- io.opencensus.tags.propagation.TagContextTextFormat
-
- Direct Known Subclasses:
CorrelationContextFormat
,NoopTags.NoopTagContextTextFormat
public abstract class TagContextTextFormat extends java.lang.Object
Object for injecting and extractingTagContext
as text into carriers that travel in-band across process boundaries. Tags 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 tags and the server-side extracts them.
Example of usage on the client:
private static final Tagger tagger = Tags.getTagger(); private static final TagContextTextFormat textFormat = Tags.getPropagationComponent().getCorrelationContextFormat(); private static final TagContextTextFormat.Setter setter = new TagContextTextFormat.Setter<HttpURLConnection>() { public void put(HttpURLConnection carrier, String key, String value) { carrier.setRequestProperty(field, value); } }; void makeHttpRequest() { TagContext tagContext = tagger.emptyBuilder().put(K, V).build(); try (Scope s = tagger.withTagContext(tagContext)) { HttpURLConnection connection = (HttpURLConnection) new URL("http://myserver").openConnection(); textFormat.inject(tagContext, connection, httpURLConnectionSetter); // Send the request, wait for response and maybe set the status if not ok. } }
Example of usage on the server:
private static final Tagger tagger = Tags.getTagger(); private static final TagContextTextFormat textFormat = Tags.getPropagationComponent().getCorrelationContextFormat(); private static final TagContextTextFormat.Getter<HttpRequest> getter = ...; void onRequestReceived(HttpRequest request) { TagContext tagContext = textFormat.extract(request, getter); try (Scope s = tagger.withTagContext(tagContext)) { // Handle request and send response back. } }
- Since:
- 0.21
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
TagContextTextFormat.Getter<C>
Class that allows aTagContextTextFormat
to read propagated fields from a carrier.static class
TagContextTextFormat.Setter<C>
Class that allows aTagContextTextFormat
to set propagated fields into a carrier.
-
Constructor Summary
Constructors Constructor Description TagContextTextFormat()
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description abstract <C> TagContext
extract(C carrier, TagContextTextFormat.Getter<C> getter)
Extracts the tag context from upstream.abstract java.util.List<java.lang.String>
fields()
The propagation fields defined.abstract <C> void
inject(TagContext tagContext, C carrier, TagContextTextFormat.Setter<C> setter)
Injects the tag context downstream.
-
-
-
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(TagContext, 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.21
-
inject
public abstract <C> void inject(TagContext tagContext, C carrier, TagContextTextFormat.Setter<C> setter) throws TagContextSerializationException
Injects the tag context downstream. For example, as http headers.- Parameters:
tagContext
- the tag context.carrier
- holds propagation fields. For example, an outgoing message or http request.setter
- invoked for each propagation key to add or remove.- Throws:
TagContextSerializationException
- if the given tag context cannot be serialized.- Since:
- 0.21
-
extract
public abstract <C> TagContext extract(C carrier, TagContextTextFormat.Getter<C> getter) throws TagContextDeserializationException
Extracts the tag 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:
TagContextDeserializationException
- if the input is invalid- Since:
- 0.21
-
-