Package brave.propagation

Class ExtraFieldPropagation<K>

java.lang.Object

brave.propagation.ExtraFieldPropagation<K>

All Implemented Interfaces:

Propagation<K>

public final class ExtraFieldPropagation<K>
extends Object
implements Propagation<K>

Allows you to propagate predefined request-scoped fields, usually but not always HTTP headers.

For example, if you are in a Cloud Foundry environment, you might want to pass the request ID:

 // when you initialize the builder, define the extra field you want to propagate
 tracingBuilder.propagationFactory(
   ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, "x-vcap-request-id")
 );

 // later, you can tag that request ID or use it in log correlation
 requestId = ExtraFieldPropagation.current("x-vcap-request-id");
 

You may also need to propagate a trace context you aren't using. For example, you may be in an Amazon Web Services environment, but not reporting data to X-Ray. To ensure X-Ray can co-exist correctly, pass-through its tracing header like so.

 tracingBuilder.propagationFactory(
   ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, "x-amzn-trace-id")
 );
 

Nested Class Summary

Nested classes/interfaces inherited from interface brave.propagation.Propagation

Propagation.Getter<C,K>, Propagation.KeyFactory<K>, Propagation.Setter<C,K>

Field Summary

Fields inherited from interface brave.propagation.Propagation

B3_STRING

Method Summary

Modifier and Type	Method	Description
static String	current(String name)	Returns the value of the field with the specified key or null if not available
<C> TraceContext.Extractor<C>	extractor(Propagation.Getter<C,K> getter)
static String	get(TraceContext context, String name)	Returns the value of the field with the specified key or null if not available
<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.
static Propagation.Factory	newFactory(Propagation.Factory delegate, String... names)	Wraps an underlying propagation implementation, pushing one or more fields
static Propagation.Factory	newFactory(Propagation.Factory delegate, Collection<String> names)	Wraps an underlying propagation implementation, pushing one or more fields

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newFactory

public static Propagation.Factory newFactory(Propagation.Factory delegate,
                                             String... names)

Wraps an underlying propagation implementation, pushing one or more fields

newFactory

public static Propagation.Factory newFactory(Propagation.Factory delegate,
                                             Collection<String> names)

Wraps an underlying propagation implementation, pushing one or more fields

current

@Nullable
public static String current(String name)

Returns the value of the field with the specified key or null if not available

get

@Nullable
public static String get(TraceContext context,
                         String name)

Returns the value of the field with the specified key or null if not available

keys

public List<K> keys()

Description copied from interface: Propagation

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.

Specified by:

keys in interface Propagation<K>

injector

public <C> TraceContext.Injector<C> injector(Propagation.Setter<C,K> setter)

Description copied from interface: Propagation

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)

Specified by:

injector in interface Propagation<K>

Parameters:

setter - invoked for each propagation key to add.

extractor

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

Specified by:

extractor in interface Propagation<K>

Parameters:

getter - invoked for each propagation key to get.