brown.tracingplane

Interface TransitLayer

All Known Implementing Classes:

NoOpTransitLayer, ThreadLocalTransitLayer

public interface TransitLayer

Maintains BaggageContext instances for requests. Most TransitLayer implementations will store BaggageContext instances using thread-local storage; this interface primarily exists to support wrappers to other implementations (e.g., OpenTracing).

The static methods in the ActiveBaggage interface proxy to a TransitLayer implementation. Typically this implementation will be ThreadLocalTransitLayer, which maintains an active BaggageContext instance using thread-local storage.

In general, TransitLayer implementations are responsible for maintaining BaggageContext instances while executions run. They use the notion of an "active" context which represents the BaggageContext for the current execution. Implicitly, if the current execution has no BaggageContext, it is the same as having an empty context.

A TransitLayer implementation typically maintains the active BaggageContext using thread-local storage. The purpose of this interface is to enable other implementations to plug in to existing instrumentation.

TransitLayer also provides methods that mirror those of BaggageProvider, such as branch() which corresponds to BaggageProvider.branch(BaggageContext). These methods simply proxy the BaggageProvider method, passing the currently active BaggageContext.

All TransitLayer implementations must have a one-argument constructor that receives the BaggageProvider to use.

Method Summary

Modifier and Type	Method and Description
BaggageContext	branch() Create and return a branched copy of the currently active baggage context.
byte[]	branchBytes() Create and return a branched, serialized copy of the currently active baggage context.
void	discard() Discard the currently active BaggageContext.
void	join(BaggageContext otherContext) Merges the contents of otherContext into the currently active context.
void	join(byte[] serialized, int offset, int length) Deserializes the provided context and merges it into the currently active context.
void	join(java.nio.ByteBuffer serializedContext) Deserializes the provided context and merges it into the currently active context.
BaggageContext	peek() Gets the currently active BaggageContext.
void	set(BaggageContext baggage) Discards the currently active BaggageContext, then activates the provided baggage.
void	set(byte[] serialized, int offset, int length) Deserializes the provided context and merges it into the currently active context.
void	set(java.nio.ByteBuffer serializedContext) Deserializes the provided context, discards any currently active context, and replaces it with the deserialized context.
BaggageContext	take() Gets and removes the currently active BaggageContext.
byte[]	takeBytes() Gets, removes, and serializes the currently active BaggageContext.
void	update(BaggageContext baggage) Sets the currently active BaggageContext.

Method Detail

discard

void discard()

Discard the currently active BaggageContext.

branch

BaggageContext branch()

Create and return a branched copy of the currently active baggage context. Typically, this will just duplicate the active context or increment a reference count. Sometimes it will create a new instance, or even modify the contents of the branched context.

Returns:

a baggage instance branched from the currently active context, possibly null

branchBytes

byte[] branchBytes()

Create and return a branched, serialized copy of the currently active baggage context. Typically, this will just duplicate the active context or increment a reference count. Sometimes it will create a new instance, or even modify the contents of the branched context.

Returns:

a baggage instance branched from the currently active context and serialized, possibly null

join

void join(BaggageContext otherContext)

Merges the contents of otherContext into the currently active context. otherContext should not be reused after calling this method, and should be treated as discarded.

Parameters:

otherContext - another baggage context, possibly null

join

void join(java.nio.ByteBuffer serializedContext)

Deserializes the provided context and merges it into the currently active context.

Parameters:

serializedContext - a serialized baggage context, possibly null

join

void join(byte[] serialized,
          int offset,
          int length)

Deserializes the provided context and merges it into the currently active context.

Parameters:

serializedContext - a serialized baggage context, possibly null

set

void set(BaggageContext baggage)

Discards the currently active BaggageContext, then activates the provided baggage. If baggage is just a modified version of the currently active BaggageContext, then it is better to use the update(BaggageContext) method instead.

Parameters:

baggage - The new baggage context to activate.

set

void set(java.nio.ByteBuffer serializedContext)

Deserializes the provided context, discards any currently active context, and replaces it with the deserialized context.

Parameters:

serializedContext - a serialized baggage context, possibly null

set

void set(byte[] serialized,
         int offset,
         int length)

Deserializes the provided context and merges it into the currently active context.

Parameters:

serialized - a serialized baggage context, possibly null

offset - offset into the byte array

length - length of serialized bytes

take

BaggageContext take()

Gets and removes the currently active BaggageContext. After calling this method, there will be no active BaggageContext.

Returns:

the current BaggageContext.

takeBytes

byte[] takeBytes()

Gets, removes, and serializes the currently active BaggageContext. After calling this method, there will be no active BaggageContext.

Returns:

the current BaggageContext.

peek

BaggageContext peek()

Gets the currently active BaggageContext. The BaggageContext instance remains active after calling this method. Use take() to if you wish to get and remove the currently active context.

Returns:

the active BaggageContext

update

void update(BaggageContext baggage)

Sets the currently active BaggageContext. A call to this method implies that the provided context argument is an updated version of the active context. Conversely, if you intend to replace the currently active context (e.g., because a different execution is beginning), use the set(BaggageContext) method.

Parameters:

context - an updated version of the currently active baggage context.