Package io.opencensus.trace.propagation

Class BinaryFormat

  • Direct Known Subclasses:
    BinaryFormat.NoopBinaryFormat, BinaryFormatImpl
    public abstract class BinaryFormat
extends java.lang.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 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:
        java.lang.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:
        java.lang.NullPointerException - if the spanContext is null.
        Since:
        0.7

      • fromBinaryValue

        @Deprecated
public SpanContext fromBinaryValue​(byte[] bytes)
                            throws java.text.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:
        java.lang.NullPointerException - if the input is null.
        java.text.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:
        java.lang.NullPointerException - if the input is null.
        SpanContextParseException - if the version is not supported or the input is invalid
        Since:
        0.7

      • getNoopBinaryFormat

        static BinaryFormat getNoopBinaryFormat()
        Returns the no-op implementation of the BinaryFormat.
        Returns:
        the no-op implementation of the BinaryFormat.