Custom Builds

Default Distribution

The default Tracing Plane distribution includes all optional components and static APIs, and configures the default Baggage Context and Transit Layer implementations.

<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>tracingplane</artifactId>
	<version>1.0</version>
</dependency>

However, in some cases you may not wish to use the defaults. The Tracing Plane can be customized as follows.

Transit Layer

The Transit Layer is optional. The default distribution includes the transit layer, and configures it to use a thread-local storage implementation. The implementation is controlled through configuration, or it can be removed entirely by omitting the transit layer dependency, which is the following:

<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>transitlayer</artifactId>
	<version>1.0</version>
</dependency>

If the transit layer is included as a dependency, the baggage.transit configuration key controls the implementation used by the transit layer static API, by default:

baggage.transit = "brown.tracingplane.impl.ThreadLocalTransitLayerFactory"

It can be disabled by setting:

baggage.transit = "brown.tracingplane.impl.NoOpTransitLayerFactory"

BaggageContext implementation

The Tracing Plane actually includes several BaggageContext implementations. The default distribution uses the full-featured BDL BaggageContext:

<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>bdl-baggagecontext</artifactId>
	<version>1.0</version>
</dependency>

This dependency is necessary if you're using BDL. However, if you are only propagating BaggageContexts, and do not use BDL, you can switch to a lightweight atom-only context:

<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>atomlayer-baggagecontext</artifactId>
	<version>1.0</version>
</dependency>

Finally, if you wish to interact with nested baggage contexts (ie, the baggage protocol) but again, do not wish to use BDL, you can switch to a baggage protocol context:

<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>baggageprotocol-baggagecontext</artifactId>
	<version>1.0</version>
</dependency>

Typical usage of the Tracing Plane is to configure a process-wide baggage context provider and invoke its methods using a static API:

<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>baggagecontext-staticapi</artifactId>
	<version>1.0</version>
</dependency>

This is included in the default Tracing Plane distributions. If the static API is used, the baggage.provider configuration key controls the implementation used, by default:

baggage.provider = "brown.tracingplane.impl.BDLContextProviderFactory"

To set it to the atom-only Baggage Context:

baggage.provider = "brown.tracingplane.impl.AtomContextProviderFactory"

To set it to the baggage protocol's nested Baggage Context:

baggage.provider = "brown.tracingplane.impl.NestedBaggageContextProviderFactory"

To disable it entirely, and use empty Baggage Contexts:

baggage.provider = "brown.tracingplane.impl.NoOpBaggageContextProviderFactory"

Note: all of the above baggage contexts, with the exception of the no-op context, are interoperable between processes. That is, the BDL context uses the baggage protocol, which represents data using atoms. Changing baggage providers is simply available as an option to use a smaller footprint if the full features aren't necessary.

Examples

Lightweight Propagation

Suppose you want to skip using BDL entirely, but still propagate atoms, and still use the static APIs. You would include the following:

<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>atomlayer-baggagecontext</artifactId>
	<version>1.0</version>
</dependency>
<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>baggagecontext-staticapi</artifactId>
	<version>1.0</version>
</dependency>
<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>transitlayer</artifactId>
	<version>1.0</version>
</dependency>

You would also configure baggage.provider and baggage.transit as follows:

baggage.transit = "brown.tracingplane.impl.ThreadLocalTransitLayerFactory"
baggage.provider = "brown.tracingplane.impl.AtomContextProviderFactory"

No-op Propagation / Instrumentation

Suppose you are instrumenting your system and you don't need to propagate anything at the moment. If you wanted to avoid the full dependency at this time, you would include:

<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>baggagecontext-staticapi</artifactId>
	<version>1.0</version>
</dependency>
<dependency>
	<groupId>brown.tracingplane</groupId>
	<artifactId>transitlayer</artifactId>
	<version>1.0</version>
</dependency>

You would also configure baggage.provider and baggage.transit as follows:

baggage.transit = "brown.tracingplane.impl.NoOpTransitLayerFactory"
baggage.provider = "brown.tracingplane.impl.NoOpBaggageContextProviderFactory"