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

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static interface`	`BaggageField.ValueUpdater`	Used to decouple baggage value updates from `TraceContext` or `TraceContextOrSamplingFlags` storage.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`static BaggageField`	`create(String name)`
`boolean`	`equals(Object o)`	Returns true for any baggage field with the same name (case insensitive).
`static List<BaggageField>`	`getAll()`	Deprecated. Since 5.12 use `getAllValues(TraceContext)`
`static List<BaggageField>`	`getAll(TraceContext context)`	Deprecated. Since 5.12 use `getAllValues(TraceContext)`
`static List<BaggageField>`	`getAll(TraceContextOrSamplingFlags extracted)`	Deprecated. Since 5.12 use `getAllValues(TraceContext)`
`static Map<String,String>`	`getAllValues()`	Like `getAllValues(TraceContext)` except against the current trace context.
`static Map<String,String>`	`getAllValues(TraceContext context)`	Returns a map of all name to non-{@code null} value pairs in the extracted result.
`static Map<String,String>`	`getAllValues(TraceContextOrSamplingFlags extracted)`	Returns a map of all name to non-{@code null} value pairs in the extracted result.
`static BaggageField`	`getByName(TraceContextOrSamplingFlags extracted, String name)`	Looks up the field by `name`, useful for when you do not have a reference to it.
`static BaggageField`	`getByName(TraceContext context, String name)`	Looks up the field by `name`, useful for when you do not have a reference to it.
`static BaggageField`	`getByName(String name)`	Like `getByName(TraceContext, String)` except against the current trace context.
`String`	`getValue()`	Like `getValue(TraceContext)` except against the current trace context.
`String`	`getValue(TraceContext context)`	Returns the most recent value for this field in the context or null if unavailable.
`String`	`getValue(TraceContextOrSamplingFlags extracted)`	Like `getValue(TraceContext)` except for use cases that precede a span.
`int`	`hashCode()`	Returns the same value for any baggage field with the same name (case insensitive).
`String`	`name()`	The non-empty name of the field.
`String`	`toString()`
`boolean`	`updateValue(TraceContextOrSamplingFlags extracted, String value)`	Like `updateValue(TraceContext, String)` except for use cases that precede a span.
`boolean`	`updateValue(TraceContext context, String value)`	Updates the value of this field, or ignores if read-only or not configured.
`boolean`	`updateValue(String value)`	Like `updateValue(TraceContext, String)` except against the current trace context.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - create
```
public static BaggageField create(String name)
```
    Parameters:
    
    name - See name()
    
    Since:
    
    5.11
  - getAll
```
@Deprecated
public static List<BaggageField> getAll(@Nullable
                                        TraceContext context)
```
    Deprecated.
    Since 5.12 use getAllValues(TraceContext)
  - getAll
```
@Deprecated
public static List<BaggageField> getAll(TraceContextOrSamplingFlags extracted)
```
    Deprecated.
    Since 5.12 use getAllValues(TraceContext)
  - getAll
```
@Deprecated
@Nullable
public static List<BaggageField> getAll()
```
    Deprecated.
    Since 5.12 use getAllValues(TraceContext)
  - getAllValues
```
public static Map<String,String> getAllValues(@Nullable
                                                    TraceContext context)
```
    Returns a map of all name to non-{@code null} value pairs in the extracted result.
    
    Since:
    
    5.12
    
    See Also:
    
    getAllValues(TraceContextOrSamplingFlags)
  - getAllValues
```
public static Map<String,String> getAllValues(TraceContextOrSamplingFlags extracted)
```
    Returns a map of all name to non-{@code null} value pairs in the extracted result.
    
    Since:
    
    5.12
    
    See Also:
    
    getAllValues(TraceContext)
  - getAllValues
```
@Nullable
public static Map<String,String> getAllValues()
```
    Like getAllValues(TraceContext) except against the current trace context.
    Prefer getAllValues(TraceContext) if you have a reference to the trace context.
    
    Since:
    
    5.12
  - getByName
```
@Nullable
public static BaggageField getByName(@Nullable
                                     TraceContext context,
                                     String name)
```
    Looks up the field by name, useful for when you do not have a reference to it. In general, BaggageFields should be referenced directly as constants where possible.
    
    Since:
    
    5.11
  - getByName
```
@Nullable
public static BaggageField getByName(TraceContextOrSamplingFlags extracted,
                                     String name)
```
    Looks up the field by name, useful for when you do not have a reference to it. In general, BaggageFields should be referenced directly as constants where possible.
    
    Since:
    
    5.11
  - getByName
```
@Nullable
public static BaggageField getByName(String name)
```
    Like getByName(TraceContext, String) except against the current trace context.
    Prefer getByName(TraceContext, String) if you have a reference to the trace context.
    
    Since:
    
    5.11
  - name
```
public final String name()
```
    The non-empty name of the field. Ex "userId".
    For example, if using log correlation and with field named "userId", the value becomes the log variable %{userId} when the span is next made current.
    
    Since:
    
    5.11
    
    See Also:
    
    getByName(TraceContext, String), CorrelationScopeConfig.SingleCorrelationField.name()
  - getValue
```
@Nullable
public String getValue(@Nullable
                       TraceContext context)
```
    Returns the most recent value for this field in the context or null if unavailable.
    The result may not be the same as the one extracted from the incoming context because updateValue(String) can override it.
    
    Since:
    
    5.11
  - getValue
```
@Nullable
public String getValue()
```
    Like getValue(TraceContext) except against the current trace context.
    Prefer getValue(TraceContext) if you have a reference to the trace context.
    
    Since:
    
    5.11
  - getValue
```
@Nullable
public String getValue(TraceContextOrSamplingFlags extracted)
```
    Like getValue(TraceContext) except for use cases that precede a span. For example, a trace ID context.
    
    Since:
    
    5.11
  - updateValue
```
public boolean updateValue(@Nullable
                           TraceContext context,
                           @Nullable
                           String value)
```
    Updates the value of this field, or ignores if read-only or not configured.
    
    Since:
    
    5.11
  - updateValue
```
public boolean updateValue(TraceContextOrSamplingFlags extracted,
                           @Nullable
                           String value)
```
    Like updateValue(TraceContext, String) except for use cases that precede a span. For example, a trace ID context.
    
    Since:
    
    5.11
  - updateValue
```
public boolean updateValue(String value)
```
    Like updateValue(TraceContext, String) except against the current trace context.
    Prefer updateValue(TraceContext, String) if you have a reference to the trace context.
    
    Since:
    
    5.11
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - equals
```
public final boolean equals(Object o)
```
    Returns true for any baggage field with the same name (case insensitive).
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public final int hashCode()
```
    Returns the same value for any baggage field with the same name (case insensitive).
    
    Overrides:
    
    hashCode in class Object

Class BaggageField

Usage

Appropriate usage

Background

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

create

getAll

getAll

getAll

getAllValues

getAllValues

getAllValues

getByName

getByName

getByName

name

getValue

getValue

getValue

updateValue

updateValue

updateValue

toString

equals

hashCode