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	Description
BinaryFormat()

Method Summary

Modifier and Type	Method	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 Object

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

Constructor Details

BinaryFormat

public BinaryFormat()

Method Details

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