Package brave.baggage

Class BaggageField

java.lang.Object
brave.baggage.BaggageField
public final class BaggageField
extends Object
Defines a trace context scoped field, usually but not always analogous to an HTTP header. Fields will be no-op unless BaggagePropagation is configured.

For example, if you have a need to know a specific request's country code in a downstream service, you can propagate it through the trace: 


 // Configure your baggage field
 COUNTRY_CODE = BaggageField.create("country-code");

Usage

As long as a field is configured with BaggagePropagation, local reads and updates are possible in-process.

Ex. once added to `BaggagePropagation`, you can call below to affect the country code of the current trace context: 


 COUNTRY_CODE.updateValue("FO");
 String countryCode = COUNTRY_CODE.get();

Or, if you have a reference to a trace context, it is more efficient to use it explicitly: 


 COUNTRY_CODE.updateValue(span.context(), "FO");
 String countryCode = COUNTRY_CODE.get(span.context());
 Tags.BAGGAGE_FIELD.tag(COUNTRY_CODE, span);

Correlation

You can also integrate baggage with other correlated contexts such as logging: 


 import brave.baggage.BaggagePropagationConfig.SingleBaggageField;
 import brave.baggage.CorrelationScopeConfig.SingleCorrelationField;

 AMZN_TRACE_ID = BaggageField.create("x-amzn-trace-id");

 // Allow logging patterns like %X{traceId} %X{x-amzn-trace-id}
 decorator = MDCScopeDecorator.newBuilder()
                              .add(SingleCorrelationField.create(AMZN_TRACE_ID)).build()

 tracingBuilder.propagationFactory(BaggagePropagation.newFactoryBuilder(B3Propagation.FACTORY)
                                                     .add(SingleBaggageField.remote(AMZN_TRACE_ID))
                                                     .build())
               .currentTraceContext(ThreadLocalCurrentTraceContext.newBuilder()
                                                                  .addScopeDecorator(decorator)
                                                                  .build())

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!

Background

The name Baggage was first introduced by Brown University in Pivot Tracing as maps, sets and tuples. They then spun baggage out as a standalone component, BaggageContext and considered some of the nuances of making it general purpose. The implementations proposed in these papers are different to the implementation here, but conceptually the goal is the same: to propagate "arbitrary stuff" with a request.
Since:
5.11
See Also:
BaggagePropagation, CorrelationScopeConfig