io.opentelemetry.trace

Class TraceId

java.lang.Object

io.opentelemetry.trace.TraceId

@Immutable
public final class TraceId
extends Object

Helper methods for dealing with a trace identifier. A valid trace identifier is a 16-byte array with at least one non-zero byte. In base-16 representation, a 32 character hex String, where at least one of the characters is not a '0'.

Since:

0.1.0

Method Summary

Modifier and Type	Method and Description
static byte[]	bytesFromHex(String src, int srcOffset) Returns a TraceId built from a lowercase base16 representation.
static String	bytesToHex(byte[] traceId) Returns the lowercase base16 encoding of this TraceId.
static void	copyHexInto(byte[] traceId, char[] dest, int destOffset) Copies the lowercase base16 representations of the TraceId into the dest beginning at the destOffset offset.
static String	fromLongs(long idHi, long idLo) Constructs a TraceId whose representation is specified by two long values representing the lower and higher parts.
static int	getHexLength() Returns the length of the base16 (hex) representation of the TraceId.
static String	getInvalid() Returns the invalid TraceId.
static int	getSize() Returns the size in bytes of the TraceId.
static long	getTraceIdRandomPart(CharSequence traceId) Returns the rightmost 8 bytes of the trace-id as a long value.
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 Detail

getSize

public static int getSize()

Returns the size in bytes of the TraceId.

Returns:

the size in bytes of the TraceId.

Since:

0.1.0

getHexLength

public static int getHexLength()

Returns the length of the base16 (hex) representation of the TraceId.

Since:

0.8.0

getInvalid

public static String getInvalid()

Returns the invalid TraceId. All bytes are '\0'.

Returns:

the invalid TraceId.

Since:

0.1.0

fromLongs

public static String fromLongs(long idHi,
                               long idLo)

Constructs a TraceId whose representation is specified by 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 make the new TraceId invalid.

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

Parameters:

idHi - the higher part of the TraceId.

idLo - the lower part of the TraceId.

Since:

0.1.0

bytesFromHex

public static byte[] bytesFromHex(String 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.1.0

copyHexInto

public static void copyHexInto(byte[] traceId,
                               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.getSize() is greater than dest.length.

Since:

0.1.0

isValid

public static boolean isValid(CharSequence traceId)

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

bytesToHex

public static String bytesToHex(byte[] traceId)

Returns the lowercase base16 encoding of this TraceId.

Returns:

the lowercase base16 encoding of this TraceId.

Since:

0.1.0

getTraceIdRandomPart

public static long getTraceIdRandomPart(CharSequence traceId)

Returns the rightmost 8 bytes of the trace-id as a long value. This is used in ProbabilitySampler.

This method is marked as internal and subject to change.

Returns:

the rightmost 8 bytes of the trace-id as a long value.