io.opentelemetry.trace

Class TraceId

java.lang.Object

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

Constructor Summary

Constructors

Constructor and Description
TraceId(long idHi, long idLo) Constructs a TraceId whose representation is specified by two long values representing the lower and higher parts.

Method Summary

Modifier and Type	Method and 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, int srcOffset) Returns a TraceId whose representation is copied from the src beginning at the srcOffset offset.
static TraceId	fromLowerBase16(CharSequence src, int srcOffset) Returns a TraceId built from a lowercase base16 representation.
static TraceId	getInvalid() Returns the invalid TraceId.
static int	getSize() Returns the size in bytes of the TraceId.
long	getTraceRandomPart() Returns the rightmost 8 bytes of the trace-id as a long value.
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 java.lang.Object

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

Constructor Detail

TraceId

public TraceId(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 fromBytes(byte[], int) 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

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

getInvalid

public static TraceId getInvalid()

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

Returns:

the invalid TraceId.

Since:

0.1.0

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.getSize() is greater than src.length.

Since:

0.1.0

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.getSize() is greater than dest.length.

Since:

0.1.0

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

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.getSize() is greater than dest.length.

Since:

0.1.0

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

toLowerBase16

public String toLowerBase16()

Returns the lowercase base16 encoding of this TraceId.

Returns:

the lowercase base16 encoding of this TraceId.

Since:

0.1.0

equals

public boolean equals(@Nullable
                      Object obj)

Overrides:

equals in class Object

getTraceRandomPart

public long getTraceRandomPart()

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.

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>