This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Documentation Grafana documentation Data sources Tempo Query tracing data TraceQL query examples

TraceQL query examples

Use these TraceQL queries in Grafana Explore with a Tempo data source. Adjust service names, routes, and attribute values to match your environment.

These examples use OpenTelemetry semantic conventions. If your instrumentation uses different attribute names, substitute them in the queries.

For the full TraceQL syntax, refer to Construct a TraceQL query. For an extended recipe collection, refer to the TraceQL cookbook for Grafana Cloud Traces.

Find error spans

Filter by error status or HTTP error codes:

traceql Copy

{ status = error }

traceql Copy

{ span.http.status_code >= 500 }

traceql Copy

{ span.http.status_code > 399 }

Find slow requests

Filter by span duration. Common thresholds are 1 second and 5 seconds:

traceql Copy

{ duration > 1s }

traceql Copy

{ duration > 5s }

Filter a specific endpoint by duration:

traceql Copy

{ span.http.url = "/api/checkout" && duration > 2s }

Find exceptions by type

Query exception events recorded on spans. Exception data uses the event scope because OpenTelemetry records exceptions as span events:

traceql Copy

{ event.exception.message =~ "context cancelled" }

traceql Copy

{ event.exception.type = "NotFoundException" }

Find error spans that have an exception message:

traceql Copy

{ status = error && event.exception.message != "" }

Filter by service

Select spans from a specific service or match services by pattern. You can use the Service Graph view to identify which services have high error rates or latency, then query those services with TraceQL.

traceql Copy

{ resource.service.name = "checkout" }

traceql Copy

{ resource.service.name =~ "payment.*" && status = error }

Find errors and slow spans together

Combine error status and duration filters to identify likely root causes:

traceql Copy

{ resource.service.name = "api" && status = error && duration > 1s }

Analyze service dependencies

Find errors on a specific API path:

traceql Copy

{ span.http.url =~ ".*/api/.*" && span.http.status_code >= 500 }

Use the descendant operator (>>) to find traces where a frontend service calls a downstream service that errors:

traceql Copy

{ resource.service.name = "frontend" } >> { resource.service.name = "database" && status = error }

Query rate and count metrics

Run these in Metrics mode in Explore. TraceQL metrics queries have a default 24-hour time-range limit:

traceql Copy

{ } | rate()

traceql Copy

{ status = error } | rate()

traceql Copy

{ resource.service.name = "api" } | count_over_time()

traceql Copy

{ duration > 1s } | rate()

Filter by region or environment

Narrow results to a specific cloud region or deployment environment:

traceql Copy

{ resource.cloud.region = "us-east-1" && status = error }

traceql Copy

{ resource.deployment.environment = "production" && duration > 2s }

Use dashboard variables

Replace hard-coded values with dashboard variables when using these queries in panels. For example, using a $service variable:

traceql Copy

{ resource.service.name = "$service" && status = error }

More resources

• TraceQL cookbook for Grafana Cloud Traces - Extended recipe collection with additional examples
• Construct a TraceQL query - Full TraceQL syntax, scopes, and operators
• Query tracing data - Query editor modes and options
• Service Graph and Service Graph view - Visualize service dependencies