Class TraceQL
String q = TraceQL.span(Map.of("resource.service.name", "api"))
.and("duration", ">", "200ms")
.select("span.http.status_code")
.toString();
// { resource.service.name = "api" && span:duration > 200ms } | select(span.http.status_code)
Field names need a scope (resource., span., event., link.,
instrumentation., or . for span or resource) or must be an intrinsic (
name, status, kind, duration, span:*, trace:*, …).
duration is written as span:duration. Attribute names with spaces or other
special characters are quoted after the scope (span."grow weird.key"). Unknown scopes,
intrinsics and operators throw ValidationException at once, because some Tempo endpoints
silently ignore an invalid query.
Values: strings are quoted and escaped (\ " and control characters), except
duration literals on duration fields (200ms), ok|error|unset on status
and span kinds on kind. Integers, decimals (1.5, 2.0) and booleans are
literals; a Duration becomes the largest exact unit (1500ms, 2s).
-
Field Summary
FieldsModifier and TypeFieldDescriptionComparison operators accepted byand(java.lang.String, java.lang.String, java.lang.Object)andor(java.lang.String, java.lang.String, java.lang.Object).Attribute scopes (""is the unscoped.nameform).Span-set operators accepted bystructural(String, TraceQL). -
Method Summary
Modifier and TypeMethodDescriptionstructural("<<", other): spans of other that are ancestors.Adds&& field op valueto the last span-set filter.build()The TraceQL text (same astoString()).static StringLight client-side check of a TraceQL text: it must start with an opening brace, and quotes, braces and parentheses must balance.structural(">", other): spans of other that are direct children.descendant(TraceQL other) structural(">>", other): spans of other that are descendants.static StringRenders a duration with the largest exact unit (1h,90s,200ms,1500us,7ns).booleanstatic StringRenders a field name: validates the scope or intrinsic and quotes odd attribute names.inthashCode()Adds|| field op valueto the last span-set filter.structural("<", other): spans of other that are direct parents.static StringQuotes text as a TraceQL string literal:"…"with\,", newline, tab and carriage return escaped; other characters (including Unicode) pass through.Adds fields to| select(…)so search returns them on each matched span.selects()The selected fields.structural("~", other): spans of other that are siblings.static TraceQLspan()An empty span-set filter ({}, every span).static TraceQLA span-set filter with onefield = valuecondition per entry, joined with&&.structural(String op, TraceQL other) Joins another query's span sets with a span-set operator:>(child),>>(descendant),<(parent),<<(ancestor),~(sibling),&&or||.toString()static StringRenders a value for a field already rendered byfield(String).static TraceQLA span-set filter with one condition:{ field op value }.
-
Field Details
-
OPERATORS
Comparison operators accepted byand(java.lang.String, java.lang.String, java.lang.Object)andor(java.lang.String, java.lang.String, java.lang.Object). -
STRUCTURAL_OPERATORS
Span-set operators accepted bystructural(String, TraceQL). -
SCOPES
Attribute scopes (""is the unscoped.nameform).
-
-
Method Details
-
span
An empty span-set filter ({}, every span).- Returns:
- builder
-
span
A span-set filter with onefield = valuecondition per entry, joined with&&. The order is the map's iteration order for aLinkedHashMaporSortedMap, else sorted by field name (soMap.of(…)renders the same text every time).- Parameters:
filters- field → value- Returns:
- builder
- Throws:
ValidationException- for an invalid field or value
-
where
A span-set filter with one condition:{ field op value }.- Parameters:
field- field nameop- comparison operatorvalue- value- Returns:
- builder
-
field
Renders a field name: validates the scope or intrinsic and quotes odd attribute names.- Parameters:
name- field name, e.g.resource.service.name,duration,span.my key- Returns:
- the TraceQL identifier
- Throws:
ValidationException- for an empty name, unknown scope or intrinsic
-
quote
Quotes text as a TraceQL string literal:"…"with\,", newline, tab and carriage return escaped; other characters (including Unicode) pass through.- Parameters:
text- text- Returns:
- quoted literal
-
value
Renders a value for a field already rendered byfield(String).- Parameters:
field- rendered fieldvalue- string, number, boolean orDuration- Returns:
- literal
- Throws:
ValidationException- for a non-finite number or another value type
-
duration
Renders a duration with the largest exact unit (1h,90s,200ms,1500us,7ns).- Parameters:
d- duration- Returns:
- TraceQL duration literal
-
and
Adds&& field op valueto the last span-set filter.- Parameters:
field- field nameop- one ofOPERATORSvalue- string, number, boolean orDuration(regex operators need a string)- Returns:
- new builder
- Throws:
ValidationException- for an invalid field, operator or value
-
or
Adds|| field op valueto the last span-set filter.- Parameters:
field- field nameop- one ofOPERATORSvalue- value- Returns:
- new builder
-
structural
Joins another query's span sets with a span-set operator:>(child),>>(descendant),<(parent),<<(ancestor),~(sibling),&&or||. The other query'sselect()is ignored.- Parameters:
op- one ofSTRUCTURAL_OPERATORSother- right-hand query- Returns:
- new builder
-
child
structural(">", other): spans of other that are direct children.- Parameters:
other- child query- Returns:
- new builder
-
descendant
structural(">>", other): spans of other that are descendants.- Parameters:
other- descendant query- Returns:
- new builder
-
parent
structural("<", other): spans of other that are direct parents.- Parameters:
other- parent query- Returns:
- new builder
-
ancestor
structural("<<", other): spans of other that are ancestors.- Parameters:
other- ancestor query- Returns:
- new builder
-
sibling
structural("~", other): spans of other that are siblings.- Parameters:
other- sibling query- Returns:
- new builder
-
select
Adds fields to| select(…)so search returns them on each matched span.- Parameters:
fields- at least one field name- Returns:
- new builder
- Throws:
ValidationException- when no field is given or a name is invalid
-
build
The TraceQL text (same astoString()).- Returns:
- query text
-
selects
The selected fields.- Returns:
- rendered field names
-
toString
-
equals
-
hashCode
public int hashCode() -
check
Light client-side check of a TraceQL text: it must start with an opening brace, and quotes, braces and parentheses must balance. Tempo's tag endpoints ignore an invalid query and return unfiltered values, so the SDK refuses obviously broken queries there.- Parameters:
query- query textoperation- operation name for the error message- Returns:
- the trimmed query
- Throws:
ValidationException- when the query is malformed
-