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

Appropriate usage

It is generally not a good idea to use the tracing system for application logic or critical code such as security context propagation.

Brave is an infrastructure library: you will create lock-in if you expose its apis into business code. Prefer exposing your own types for utility functions that use this class as this will insulate you from lock-in.

While it may seem convenient, do not use this for security context propagation as it was not designed for this use case. For example, anything placed in here can be accessed by any code in the same classloader!

Passing through alternate trace contexts

You may also need to propagate an second trace context transparently. For example, when 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")
 );

Prefixed fields

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