Class TraceId

java.lang.Object
io.opencensus.trace.TraceId
All Implemented Interfaces:
Comparable<TraceId>
@Immutable public final class TraceId extends Object implements Comparable<TraceId>
A class that represents a trace identifier. A valid trace identifier is a 16-byte array with at least one non-zero byte.
Since:
0.5

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final int
    BASE16_SIZE
     
    private final long
    idHi
     
    private final long
    idLo
     
    static final TraceId
    INVALID
    The invalid TraceId.
    private static final long
    INVALID_ID
     
    static final int
    SIZE
    The size in bytes of the TraceId.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    TraceId(long idHi, long idLo)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    compareTo(TraceId that)
     
    void
    copyBytesTo(byte[] dest, int destOffset)
    Copies the byte array representations of the TraceId into the dest beginning at the destOffset offset.
    void
    copyLowerBase16To(char[] dest, int destOffset)
    Copies the lowercase base16 representations of the TraceId into the dest beginning at the destOffset offset.
    boolean
    equals(Object obj)
     
    static TraceId
    fromBytes(byte[] src)
    Returns a TraceId built from a byte representation.
    static TraceId
    fromBytes(byte[] src, int srcOffset)
    Returns a TraceId whose representation is copied from the src beginning at the srcOffset offset.
    static TraceId
    fromLowerBase16(CharSequence src)
    Returns a TraceId built from a lowercase base16 representation.
    static TraceId
    fromLowerBase16(CharSequence src, int srcOffset)
    Returns a TraceId built from a lowercase base16 representation.
    static TraceId
    generateRandomId(Random random)
    Generates a new random TraceId.
    byte[]
    getBytes()
    Returns the 16-bytes array representation of the TraceId.
    long
    getLowerLong()
    Returns the lower 8 bytes of the trace-id as a long value, assuming little-endian order.
    int
    hashCode()
     
    boolean
    isValid()
    Returns whether the TraceId is valid.
    String
    toLowerBase16()
    Returns the lowercase base16 encoding of this TraceId.
    String
    toString()
     

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • SIZE

      public static final int SIZE
      The size in bytes of the TraceId.
      Since:
      0.5
      See Also:

    • BASE16_SIZE

      private static final int BASE16_SIZE
      See Also:

    • INVALID_ID

      private static final long INVALID_ID
      See Also:

    • INVALID

      public static final TraceId INVALID
      The invalid TraceId. All bytes are '\0'.
      Since:
      0.5

    • idHi

      private final long idHi

    • idLo

      private final long idLo

  • Constructor Details

    • TraceId

      private TraceId(long idHi, long idLo)

  • Method Details

    • fromBytes

      public static TraceId fromBytes(byte[] src)
      Returns a TraceId built from a byte representation.
      Parameters:
      src - the representation of the TraceId.
      Returns:
      a TraceId whose representation is given by the src parameter.
      Throws:
      NullPointerException - if src is null.
      IllegalArgumentException - if src.length is not SIZE.
      Since:
      0.5

    • fromBytes

      public static TraceId fromBytes(byte[] src, int srcOffset)
      Returns a TraceId whose representation is copied from the src beginning at the srcOffset offset.
      Parameters:
      src - the buffer where the representation of the TraceId is copied.
      srcOffset - the offset in the buffer where the representation of the TraceId begins.
      Returns:
      a TraceId whose representation is copied from the buffer.
      Throws:
      NullPointerException - if src is null.
      IndexOutOfBoundsException - if srcOffset+TraceId.SIZE is greater than src.length.
      Since:
      0.5

    • fromLowerBase16

      public static TraceId fromLowerBase16(CharSequence src)
      Returns a TraceId built from a lowercase base16 representation.
      Parameters:
      src - the lowercase base16 representation.
      Returns:
      a TraceId built from a lowercase base16 representation.
      Throws:
      NullPointerException - if src is null.
      IllegalArgumentException - if src.length is not 2 * TraceId.SIZE OR if the str has invalid characters.
      Since:
      0.11

    • fromLowerBase16

      public static TraceId fromLowerBase16(CharSequence src, int srcOffset)
      Returns a TraceId built from a lowercase base16 representation.
      Parameters:
      src - the lowercase base16 representation.
      srcOffset - the offset in the buffer where the representation of the TraceId begins.
      Returns:
      a TraceId built from a lowercase base16 representation.
      Throws:
      NullPointerException - if src is null.
      IllegalArgumentException - if not enough characters in the src from the srcOffset.
      Since:
      0.11

    • generateRandomId

      public static TraceId generateRandomId(Random random)
      Generates a new random TraceId.
      Parameters:
      random - the random number generator.
      Returns:
      a new valid TraceId.
      Since:
      0.5

    • getBytes

      public byte[] getBytes()
      Returns the 16-bytes array representation of the TraceId.
      Returns:
      the 16-bytes array representation of the TraceId.
      Since:
      0.5

    • copyBytesTo

      public void copyBytesTo(byte[] dest, int destOffset)
      Copies the byte array representations of the TraceId into the dest beginning at the destOffset offset.
      Parameters:
      dest - the destination buffer.
      destOffset - the starting offset in the destination buffer.
      Throws:
      NullPointerException - if dest is null.
      IndexOutOfBoundsException - if destOffset+TraceId.SIZE is greater than dest.length.
      Since:
      0.5

    • copyLowerBase16To

      public void copyLowerBase16To(char[] dest, int destOffset)
      Copies the lowercase base16 representations of the TraceId into the dest beginning at the destOffset offset.
      Parameters:
      dest - the destination buffer.
      destOffset - the starting offset in the destination buffer.
      Throws:
      IndexOutOfBoundsException - if destOffset + 2 * TraceId.SIZE is greater than dest.length.
      Since:
      0.18

    • isValid

      public boolean isValid()
      Returns whether the TraceId is valid. A valid trace identifier is a 16-byte array with at least one non-zero byte.
      Returns:
      true if the TraceId is valid.
      Since:
      0.5

    • toLowerBase16

      public String toLowerBase16()
      Returns the lowercase base16 encoding of this TraceId.
      Returns:
      the lowercase base16 encoding of this TraceId.
      Since:
      0.11

    • getLowerLong

      @Internal public long getLowerLong()
      Returns the lower 8 bytes of the trace-id as a long value, assuming little-endian order. This is used in ProbabilitySampler.

      This method is marked as internal and subject to change.

      Returns:
      the lower 8 bytes of the trace-id as a long value, assuming little-endian order.

    • equals

      public boolean equals(@Nullable Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • compareTo

      public int compareTo(TraceId that)
      Specified by:
      compareTo in interface Comparable<TraceId>