Class TraceQL

java.lang.Object
codes.grow.packages.tempo.TraceQL

public final class TraceQL extends Object
Immutable TraceQL query builder with escaping. Every method returns a new builder.

 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 Details

  • Method Details

    • span

      public static TraceQL span()
      An empty span-set filter ({}, every span).
      Returns:
      builder
    • span

      public static TraceQL span(Map<String,?> filters)
      A span-set filter with one field = value condition per entry, joined with &&. The order is the map's iteration order for a LinkedHashMap or SortedMap, else sorted by field name (so Map.of(…) renders the same text every time).
      Parameters:
      filters - field → value
      Returns:
      builder
      Throws:
      ValidationException - for an invalid field or value
    • where

      public static TraceQL where(String field, String op, Object value)
      A span-set filter with one condition: { field op value }.
      Parameters:
      field - field name
      op - comparison operator
      value - value
      Returns:
      builder
    • field

      public static String field(String name)
      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

      public static String quote(String text)
      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

      public static String value(String field, Object value)
      Renders a value for a field already rendered by field(String).
      Parameters:
      field - rendered field
      value - string, number, boolean or Duration
      Returns:
      literal
      Throws:
      ValidationException - for a non-finite number or another value type
    • duration

      public static String duration(Duration d)
      Renders a duration with the largest exact unit (1h, 90s, 200ms, 1500us, 7ns).
      Parameters:
      d - duration
      Returns:
      TraceQL duration literal
    • and

      public TraceQL and(String field, String op, Object value)
      Adds && field op value to the last span-set filter.
      Parameters:
      field - field name
      op - one of OPERATORS
      value - string, number, boolean or Duration (regex operators need a string)
      Returns:
      new builder
      Throws:
      ValidationException - for an invalid field, operator or value
    • or

      public TraceQL or(String field, String op, Object value)
      Adds || field op value to the last span-set filter.
      Parameters:
      field - field name
      op - one of OPERATORS
      value - value
      Returns:
      new builder
    • structural

      public TraceQL structural(String op, TraceQL other)
      Joins another query's span sets with a span-set operator: > (child), >> (descendant), < (parent), << (ancestor), ~ (sibling), && or ||. The other query's select() is ignored.
      Parameters:
      op - one of STRUCTURAL_OPERATORS
      other - right-hand query
      Returns:
      new builder
    • child

      public TraceQL child(TraceQL other)
      structural(">", other): spans of other that are direct children.
      Parameters:
      other - child query
      Returns:
      new builder
    • descendant

      public TraceQL descendant(TraceQL other)
      structural(">>", other): spans of other that are descendants.
      Parameters:
      other - descendant query
      Returns:
      new builder
    • parent

      public TraceQL parent(TraceQL other)
      structural("<", other): spans of other that are direct parents.
      Parameters:
      other - parent query
      Returns:
      new builder
    • ancestor

      public TraceQL ancestor(TraceQL other)
      structural("<<", other): spans of other that are ancestors.
      Parameters:
      other - ancestor query
      Returns:
      new builder
    • sibling

      public TraceQL sibling(TraceQL other)
      structural("~", other): spans of other that are siblings.
      Parameters:
      other - sibling query
      Returns:
      new builder
    • select

      public TraceQL select(String... fields)
      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

      public String build()
      The TraceQL text (same as toString()).
      Returns:
      query text
    • selects

      public List<String> selects()
      The selected fields.
      Returns:
      rendered field names
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • check

      public static String check(String query, String operation)
      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 text
      operation - operation name for the error message
      Returns:
      the trimmed query
      Throws:
      ValidationException - when the query is malformed