docs/sources/datasources/tempo/query-editor/traceql-query-examples.md
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.
{{< admonition type="tip" >}}
If a query returns no results, widen the time range and confirm the correct Tempo data source is selected.
Prefer trace-level intrinsic fields like trace:duration and trace:rootService for faster queries.
{{< /admonition >}}
Filter by error status or HTTP error codes:
{ status = error }
{ span.http.status_code >= 500 }
{ span.http.status_code > 399 }
Filter by span duration. Common thresholds are 1 second and 5 seconds:
{ duration > 1s }
{ duration > 5s }
Filter a specific endpoint by duration:
{ span.http.url = "/api/checkout" && duration > 2s }
Query exception events recorded on spans.
Exception data uses the event scope because OpenTelemetry records exceptions as span events:
{ event.exception.message =~ "context cancelled" }
{ event.exception.type = "NotFoundException" }
Find error spans that have an exception message:
{ status = error && event.exception.message != "" }
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.
{ resource.service.name = "checkout" }
{ resource.service.name =~ "payment.*" && status = error }
Combine error status and duration filters to identify likely root causes:
{ resource.service.name = "api" && status = error && duration > 1s }
Find errors on a specific API path:
{ 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:
{ resource.service.name = "frontend" } >> { resource.service.name = "database" && status = error }
Run these in Metrics mode in Explore. TraceQL metrics queries have a default 24-hour time-range limit:
{ } | rate()
{ status = error } | rate()
{ resource.service.name = "api" } | count_over_time()
{ duration > 1s } | rate()
Narrow results to a specific cloud region or deployment environment:
{ resource.cloud.region = "us-east-1" && status = error }
{ resource.deployment.environment = "production" && duration > 2s }
Replace hard-coded values with dashboard variables when using these queries in panels.
For example, using a $service variable:
{ resource.service.name = "$service" && status = error }