Skip to main content

Run a TraceQL metrics query

GET 
/v1/api/instance/:instance/traces/traceql/metrics/query_range

Runs a TraceQL metrics query over a time range. The response is in the Tempo metrics format: one time series for each group.

The query is a span selector, then a metrics function, then an optional by(...) clause: { selector } | function(...) by (attribute, ...). The supported functions are:

  • rate(): matching spans per second.
  • count_over_time(): matching spans in each step.
  • avg_over_time(attribute), min_over_time(attribute), max_over_time(attribute), sum_over_time(attribute): the average, minimum, maximum or sum of a numeric attribute, for example duration.
  • histogram_over_time(attribute): a histogram of a numeric attribute.
  • quantile_over_time(attribute, q, ...): one or more quantiles of a numeric attribute, for example quantile_over_time(duration, 0.95, 0.99).

by(...) groups the result by one or more attributes. Example: { span.http.status_code >= 500 } | rate() by (resource.service.name).

This endpoint accepts only metrics queries. Send a span selector without a metrics function to the TraceQL search endpoint, /traceql/search.

start and end are Unix epoch seconds. When you do not send them, the range is the last hour.

Required role: Viewer, Editor, or Admin

Request​

Responses​

Support

If you need assistance or have any questions, please reach out to us through: