Package io.opentelemetry.api.trace

Class 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

      All Methods Static Methods Concrete Methods 
      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.

    • Method Detail

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