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.get("x-vcap-request-id");

 // You can also set or override the value similarly, which might be needed if a new request
 ExtraFieldPropagation.get("x-country-code", "FO");
 

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")
 );
 

You can also prefix fields, if they follow a common pattern. For example, the following will propagate the field "x-vcap-request-id" as-is, but send the fields "country-code" and "user-id" on the wire as "baggage-country-code" and "baggage-user-id" respectively.

 // Setup your tracing instance with allowed fields
 tracingBuilder.propagationFactory(
   ExtraFieldPropagation.newFactoryBuilder(B3Propagation.FACTORY)
                        .addField("x-vcap-request-id")
                        .addPrefixedFields("baggage-", Arrays.asList("country-code", "user-id"))
                        .build()
 );

 // Later, you can call below to affect the country code of the current trace context
 ExtraFieldPropagation.set("country-code", "FO");
 String countryCode = ExtraFieldPropagation.get("country-code");

 // Or, if you have a reference to a trace context, use it explicitly
 ExtraFieldPropagation.set(span.context(), "country-code", "FO");
 String countryCode = ExtraFieldPropagation.get(span.context(), "country-code");
 

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ExtraFieldPropagation.FactoryBuilder

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)	Synonym for get(String)
<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
static String	get(String name)	Returns the value of the field with the specified key or null if not available.
static Map<String,String>	getAll()	Returns a mapping of fields in the current trace context, or empty if there are none.
static Map<String,String>	getAll(TraceContext context)	Returns a mapping of any fields in the trace context.
static Map<String,String>	getAll(TraceContextOrSamplingFlags extracted)	Returns a mapping of any fields in the extraction result.
<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... fieldNames)	Wraps an underlying propagation implementation, pushing one or more fields
static Propagation.Factory	newFactory(Propagation.Factory delegate, Collection<String> fieldNames)	Wraps an underlying propagation implementation, pushing one or more fields
static ExtraFieldPropagation.FactoryBuilder	newFactoryBuilder(Propagation.Factory delegate)
static void	set(TraceContext context, String name, String value)	Sets the value of the field with the specified key, or drops if not a configured field
static void	set(String name, String value)	Sets the current value of the field with the specified key, or drops if not a configured field.

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... fieldNames)

Wraps an underlying propagation implementation, pushing one or more fields

newFactory

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

Wraps an underlying propagation implementation, pushing one or more fields

newFactoryBuilder

public static ExtraFieldPropagation.FactoryBuilder newFactoryBuilder(Propagation.Factory delegate)

current

@Nullable
public static String current(String name)

Synonym for get(String)

get

@Nullable
public static String get(String name)

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

Prefer get(TraceContext, String) if you have a reference to a span.

set

public static void set(String name,
                       String value)

Sets the current value of the field with the specified key, or drops if not a configured field.

Prefer set(TraceContext, String, String) if you have a reference to a span.

getAll

public static Map<String,String> getAll()

Returns a mapping of fields in the current trace context, or empty if there are none.

Prefer set(TraceContext, String, String) if you have a reference to a span.

getAll

public static Map<String,String> getAll(TraceContextOrSamplingFlags extracted)

Returns a mapping of any fields in the extraction result.

getAll

public static Map<String,String> getAll(TraceContext context)

Returns a mapping of any fields in the trace context.

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

set

public static void set(TraceContext context,
                       String name,
                       String value)

Sets the value of the field with the specified key, or drops if not a configured field

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.