Package io.opentelemetry.api.trace

Class TraceId

java.lang.Object
io.opentelemetry.api.trace.TraceId
@Immutable public final class TraceId extends Object
Helper methods for dealing with a trace identifier. A valid trace identifier is a 32 character lowercase hex (base16) String, where at least one of the characters is not a "0".

There are two more other representation that this class helps with:

  • Bytes: a 16-byte array, where valid means that at least one of the bytes is not `\0`.
  • Long: two long values, where valid means that at least one of values is non-zero. To avoid allocating new objects this representation uses two parts, "high part" representing the left most part of the TraceId and "low part" representing the right most part of the TraceId. This is equivalent with the values being stored as big-endian.

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    fromBytes(byte[] traceIdBytes)
    Returns the lowercase hex (base16) representation of the TraceId converted from the given bytes representation, or getInvalid() if input is null or the given byte array is too short.
    static String
    fromLongs(long traceIdLongHighPart, long traceIdLongLowPart)
    Returns the bytes (16-byte array) representation of the TraceId converted from the given two long values representing the lower and higher parts.
    static String
    getInvalid()
    Returns the invalid TraceId in lowercase hex (base16) representation.
    static int
    getLength()
    Returns the length of the lowercase hex (base16) representation of the TraceId.
    static boolean
    isValid(CharSequence traceId)
    Returns whether the TraceId is valid.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • getLength

      public static int getLength()
      Returns the length of the lowercase hex (base16) representation of the TraceId.
      Returns:
      the length of the lowercase hex (base16) representation of the TraceId.

    • getInvalid

      public static String getInvalid()
      Returns the invalid TraceId in lowercase hex (base16) representation. All characters are "0".
      Returns:
      the invalid TraceId in lowercase hex (base16) representation.

    • isValid

      public static boolean isValid(CharSequence traceId)
      Returns whether the TraceId is valid. A valid trace identifier is a 32 character hex String, where at least one of the characters is not a '0'.
      Returns:
      true if the TraceId is valid.

    • fromBytes

      public static String fromBytes(byte[] traceIdBytes)
      Returns the lowercase hex (base16) representation of the TraceId converted from the given bytes representation, or getInvalid() if input is null or the given byte array is too short.

      It converts the first 26 bytes of the given byte array.

      Parameters:
      traceIdBytes - the bytes (16-byte array) representation of the TraceId.
      Returns:
      the lowercase hex (base16) representation of the TraceId.

    • fromLongs

      public static String fromLongs(long traceIdLongHighPart, long traceIdLongLowPart)
      Returns the bytes (16-byte array) representation of the TraceId converted from the given two long values representing the lower and higher parts.

      There is no restriction on the specified values, other than the already established validity rules applying to TraceId. Specifying 0 for both values will effectively return getInvalid().

      This is equivalent to calling fromBytes(byte[]) with the specified values stored as big-endian.

      Parameters:
      traceIdLongHighPart - the higher part of the long values representation of the TraceId.
      traceIdLongLowPart - the lower part of the long values representation of the TraceId.
      Returns:
      the lowercase hex (base16) representation of the TraceId.