io.opencensus.trace.propagation

Class BinaryFormat

java.lang.Object

io.opencensus.trace.propagation.BinaryFormat

public abstract class BinaryFormat
extends Object

This is a helper class for SpanContext propagation on the wire using binary encoding.

Example of usage on the client:

 private static final Tracer tracer = Tracing.getTracer();
 private static final BinaryFormat binaryFormat =
     Tracing.getPropagationComponent().getBinaryFormat();
 void onSendRequest() {
   try (Scope ss = tracer.spanBuilder("Sent.MyRequest").startScopedSpan()) {
     byte[] binaryValue = binaryFormat.toByteArray(tracer.getCurrentContext().context());
     // Send the request including the binaryValue and wait for the response.
   }
 }
 

Example of usage on the server:

 private static final Tracer tracer = Tracing.getTracer();
 private static final BinaryFormat binaryFormat =
     Tracing.getPropagationComponent().getBinaryFormat();
 void onRequestReceived() {
   // Get the binaryValue from the request.
   SpanContext spanContext = SpanContext.INVALID;
   try {
     if (binaryValue != null) {
       spanContext = binaryFormat.fromByteArray(binaryValue);
     }
   } catch (SpanContextParseException e) {
     // Maybe log the exception.
   }
   try (Scope ss =
            tracer.spanBuilderWithRemoteParent("Recv.MyRequest", spanContext).startScopedSpan()) {
     // Handle request and send response back.
   }
 }
 

Since:

0.5

Constructor Summary

Constructors

Constructor and Description
BinaryFormat()

Method Summary

Modifier and Type	Method and Description
SpanContext	fromBinaryValue(byte[] bytes) Deprecated. use fromByteArray(byte[]).
SpanContext	fromByteArray(byte[] bytes) Parses the SpanContext from a byte array using the binary format.
byte[]	toBinaryValue(SpanContext spanContext) Deprecated. use toByteArray(SpanContext).
byte[]	toByteArray(SpanContext spanContext) Serializes a SpanContext into a byte array using the binary format.

Methods inherited from class java.lang.Object

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

Constructor Detail

BinaryFormat

public BinaryFormat()

Method Detail

toBinaryValue

@Deprecated
public byte[] toBinaryValue(SpanContext spanContext)

Deprecated. use toByteArray(SpanContext).

Serializes a SpanContext into a byte array using the binary format.

Parameters:

spanContext - the SpanContext to serialize.

Returns:

the serialized binary value.

Throws:

NullPointerException - if the spanContext is null.

Since:

0.5

toByteArray

public byte[] toByteArray(SpanContext spanContext)

Serializes a SpanContext into a byte array using the binary format.

Parameters:

spanContext - the SpanContext to serialize.

Returns:

the serialized binary value.

Throws:

NullPointerException - if the spanContext is null.

Since:

0.7

fromBinaryValue

@Deprecated
public SpanContext fromBinaryValue(byte[] bytes)
                                        throws ParseException

Deprecated. use fromByteArray(byte[]).

Parses the SpanContext from a byte array using the binary format.

Parameters:

bytes - a binary encoded buffer from which the SpanContext will be parsed.

Returns:

the parsed SpanContext.

Throws:

NullPointerException - if the input is null.

ParseException - if the version is not supported or the input is invalid

Since:

0.5

fromByteArray

public SpanContext fromByteArray(byte[] bytes)
                          throws SpanContextParseException

Parses the SpanContext from a byte array using the binary format.

Parameters:

bytes - a binary encoded buffer from which the SpanContext will be parsed.

Returns:

the parsed SpanContext.

Throws:

NullPointerException - if the input is null.

SpanContextParseException - if the version is not supported or the input is invalid

Since:

0.7