Package brave.propagation

Class B3SingleFormat

java.lang.Object

brave.propagation.B3SingleFormat

public final class B3SingleFormat
extends Object

This format corresponds to the propagation key "b3" (or "B3"), which delimits fields in the following manner.

 b3: {x-b3-traceid}-{x-b3-spanid}-{if x-b3-flags 'd' else x-b3-sampled}-{x-b3-parentspanid}
 

For example, a sampled root span would look like: 4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-1

... a not yet sampled root span would look like: 4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7

... and a debug RPC child span would look like: 4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-d-5b4185666d50f68b

Like normal B3, it is valid to omit trace identifiers in order to only propagate a sampling decision. For example, the following are valid downstream hints:

• don't sample - b3: 0
• sampled - b3: 1
• debug - b3: d

Reminder: debug (previously X-B3-Flags: 1), is a boosted sample signal which is recorded to ensure it reaches the collector tier. See SamplingFlags.debug().

See B3 Propagation

Method Summary

Modifier and Type	Method	Description
static TraceContextOrSamplingFlags	parseB3SingleFormat(CharSequence b3)
static TraceContextOrSamplingFlags	parseB3SingleFormat(CharSequence value, int beginIndex, int endIndex)	This reads a trace context a sequence potentially larger than the format.
static String	writeB3SingleFormat(TraceContext context)	Writes all B3 defined fields in the trace context to a hyphen delimited string.
static byte[]	writeB3SingleFormatAsBytes(TraceContext context)	Like writeB3SingleFormat(TraceContext), but for requests with byte array or byte buffer values.
static String	writeB3SingleFormatWithoutParentId(TraceContext context)	Writes all B3 defined fields in the trace context, except parent ID, to a hyphen delimited string.
static byte[]	writeB3SingleFormatWithoutParentIdAsBytes(TraceContext context)	Like writeB3SingleFormatWithoutParentId(TraceContext), but for requests with byte array or byte buffer values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

writeB3SingleFormatWithoutParentId

public static String writeB3SingleFormatWithoutParentId(TraceContext context)

Writes all B3 defined fields in the trace context, except parent ID, to a hyphen delimited string.

This is appropriate for receivers who understand "b3" single header format, and always do work in a child span. For example, message consumers always do work in child spans, so message producers can use this format to save bytes on the wire. On the other hand, RPC clients should use writeB3SingleFormat(TraceContext) instead, as RPC servers often share a span ID with the client.

writeB3SingleFormatWithoutParentIdAsBytes

public static byte[] writeB3SingleFormatWithoutParentIdAsBytes(TraceContext context)

Like writeB3SingleFormatWithoutParentId(TraceContext), but for requests with byte array or byte buffer values. For example, ByteBuffer.wrap(byte[]) can wrap the result.

writeB3SingleFormat

public static String writeB3SingleFormat(TraceContext context)

Writes all B3 defined fields in the trace context to a hyphen delimited string. This is appropriate for receivers who understand "b3" single header format.

The parent ID is serialized in case the receiver is an RPC server. When downstream is known to be a messaging consumer, or a server that never reuses a client's span ID, prefer writeB3SingleFormatWithoutParentId(TraceContext).

writeB3SingleFormatAsBytes

public static byte[] writeB3SingleFormatAsBytes(TraceContext context)

Like writeB3SingleFormat(TraceContext), but for requests with byte array or byte buffer values. For example, ByteBuffer.wrap(byte[]) can wrap the result.

parseB3SingleFormat

@Nullable public static TraceContextOrSamplingFlags parseB3SingleFormat(CharSequence b3)

parseB3SingleFormat

@Nullable public static TraceContextOrSamplingFlags parseB3SingleFormat(CharSequence value, int beginIndex, int endIndex)

This reads a trace context a sequence potentially larger than the format. The use-case is reducing garbage, by re-using the input value across multiple parse operations.

Parameters:

value - the sequence that contains a B3 single formatted trace context

beginIndex - the inclusive begin index: index of the first character in B3 single format.

endIndex - the exclusive end index: index after the last character in B3 single format.