Class TraceIds
java.lang.Object
codes.grow.packages.tempo.tracing.query.TraceIds
Trace and span id normalisation (lower-case hex; 64-bit trace ids are left-padded to 32).
The query model (Span, Trace, TraceSummary) and TraceQueryClient.waitForTrace(java.lang.String, codes.grow.packages.tempo.tracing.query.WaitForTraceOptions) normalise ids with traceId(String) and spanId(String). Those are strict by default; for a backend with native, non-hex ids (for
example Apache SkyWalking <hex>.<n>.<ms>) hex ids are still normalised and other ids are
kept verbatim when native ids are accepted. Three scopes, narrowest first:
- per call:
withNativeIds(boolean, Supplier)/runWithNativeIds(boolean, Runnable)set the policy for the current thread while the body runs (nested calls and exceptions restore the previous policy); - per client class: a
TraceQueryClientoverridesTraceQueryClient.acceptsNativeIds()to returntrueand wraps its own parsing inwithNativeIds(acceptsNativeIds(), ...); the defaultwaitForTraceand the…Asynclookups apply it; - package-wide:
acceptNativeIds(boolean)sets the default of every thread. Prefer the scoped forms; a test that changes the default must restore the previous value.
-
Method Summary
Modifier and TypeMethodDescriptionstatic voidacceptNativeIds(boolean accept) Sets the package-wide default: whethertraceId(String)andspanId(String)keep native (non-hex) ids verbatim instead of rejecting them, on every thread that has no scoped policy (withNativeIds(boolean, java.util.function.Supplier<T>)).static booleanisValidTraceId(String id) Whetheridis a valid (normalised or normalisable) trace id.static booleanReturns whether native ids are accepted on the current thread: the policy of the innermostwithNativeIds(boolean, java.util.function.Supplier<T>)call, else the package-wide default (acceptNativeIds(boolean)).static booleanReturns the package-wide default set withacceptNativeIds(boolean), ignoring any scoped policy of the current thread.static StringNormalises a span id (16 lower-hex characters, shorter ids left-padded).static StringNormalises a hex span id likenormalizeSpanId(java.lang.String)and keeps any other non-blank id (trimmed) verbatim.static StringNormalises a trace id: trims, strips a0xprefix, lower-cases and left-pads 1–31 hex digits (for example 64-bit Zipkin/Datadog ids) to 32.static StringNormalises a hex trace id likenormalizeTraceId(java.lang.String)and keeps any other non-blank id (trimmed) verbatim.static voidrunWithNativeIds(boolean accept, Runnable body) withNativeIds(boolean, Supplier)for code without a result.static StringNormalises a span id of the query model:normalizeSpanId(java.lang.String)by default,normalizeSpanIdOrNative(java.lang.String)when native ids are accepted (nativeIdsAccepted()).static StringNormalises a trace id of the query model:normalizeTraceId(java.lang.String)by default,normalizeTraceIdOrNative(java.lang.String)when native ids are accepted (nativeIdsAccepted()).static <T> TwithNativeIds(boolean accept, Supplier<T> body) Runsbodywith native ids accepted (or not) on the current thread only; the previous policy is restored when the body returns or throws.
-
Method Details
-
normalizeTraceId
Normalises a trace id: trims, strips a0xprefix, lower-cases and left-pads 1–31 hex digits (for example 64-bit Zipkin/Datadog ids) to 32.- Parameters:
id- trace id- Returns:
- 32 lower-hex characters
- Throws:
ValidationException- when the id is not hex, too long or all zero
-
normalizeSpanId
Normalises a span id (16 lower-hex characters, shorter ids left-padded).- Parameters:
id- span id- Returns:
- 16 lower-hex characters
- Throws:
ValidationException- when the id is not hex, too long or all zero
-
isValidTraceId
Whetheridis a valid (normalised or normalisable) trace id.- Parameters:
id- candidate- Returns:
- true when
normalizeTraceId(java.lang.String)accepts it
-
acceptNativeIds
public static void acceptNativeIds(boolean accept) Sets the package-wide default: whethertraceId(String)andspanId(String)keep native (non-hex) ids verbatim instead of rejecting them, on every thread that has no scoped policy (withNativeIds(boolean, java.util.function.Supplier<T>)). Applies to this SDK package only; the default isfalse. This is process state: preferwithNativeIds(boolean, java.util.function.Supplier<T>)orTraceQueryClient.acceptsNativeIds(), and restore the previous value (nativeIdsAcceptedByDefault()) when a test changes it.- Parameters:
accept- true to accept native ids
-
nativeIdsAcceptedByDefault
public static boolean nativeIdsAcceptedByDefault()Returns the package-wide default set withacceptNativeIds(boolean), ignoring any scoped policy of the current thread.- Returns:
- true when native ids are accepted by default
-
nativeIdsAccepted
public static boolean nativeIdsAccepted()Returns whether native ids are accepted on the current thread: the policy of the innermostwithNativeIds(boolean, java.util.function.Supplier<T>)call, else the package-wide default (acceptNativeIds(boolean)).- Returns:
- true when native ids are kept verbatim
-
withNativeIds
Runsbodywith native ids accepted (or not) on the current thread only; the previous policy is restored when the body returns or throws. Other threads, and work the body hands to other threads, keep their own policy.- Type Parameters:
T- result type- Parameters:
accept- true to accept native ids while the body runsbody- code that builds or normalises ids- Returns:
- the body's result
-
runWithNativeIds
withNativeIds(boolean, Supplier)for code without a result.- Parameters:
accept- true to accept native ids while the body runsbody- code that builds or normalises ids
-
traceId
Normalises a trace id of the query model:normalizeTraceId(java.lang.String)by default,normalizeTraceIdOrNative(java.lang.String)when native ids are accepted (nativeIdsAccepted()).- Parameters:
id- trace id- Returns:
- the normalised id
- Throws:
ValidationException- when the id is invalid
-
spanId
Normalises a span id of the query model:normalizeSpanId(java.lang.String)by default,normalizeSpanIdOrNative(java.lang.String)when native ids are accepted (nativeIdsAccepted()).- Parameters:
id- span id- Returns:
- the normalised id
- Throws:
ValidationException- when the id is invalid
-
normalizeTraceIdOrNative
Normalises a hex trace id likenormalizeTraceId(java.lang.String)and keeps any other non-blank id (trimmed) verbatim.- Parameters:
id- trace id- Returns:
- the normalised or native id
- Throws:
ValidationException- when the id is null, blank, or hex but invalid
-
normalizeSpanIdOrNative
Normalises a hex span id likenormalizeSpanId(java.lang.String)and keeps any other non-blank id (trimmed) verbatim.- Parameters:
id- span id- Returns:
- the normalised or native id
- Throws:
ValidationException- when the id is null, blank, or hex but invalid
-