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.
        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.
        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.