Query Distributed Traces
query_tracesSearch distributed traces (Tempo TraceQL), newest first, to find slow, failing, or specific requests. Filter with structured params (gvc, workload, location, httpMethod, requestId, errorsOnly, minDuration) OR a raw traceql query, which REPLACES them and must embed every filter. Span attributes: resource.gvc, resource.workload, resource.location, span.http.method, span.http.url (the full URL), span.http.status_code (a string, e.g. "503"), span."guid:x-request-id". Traces exist only where tracing is enabled (spec.tracing on the GVC via update_gvc, or on the org) and only for requests sampled after that. Returns trace IDs with root span, requests seen, start time, and duration. traceId returns that one trace instead: the span tree with each span's duration, service, kind (server: a request the workload received; client: a call it made), method, path, and status; the request ids to match in access and request logs; and the error spans with their messages, to pinpoint WHERE latency or failures sit. A very large trace shows its first spans in tree order and always lists its error spans.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "query_traces"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Absolute end time (exclusive, ISO 8601). | |
| gvc | No | Filter traces to one GVC (matches the `resource.gvc` span attribute). | |
| org | No | Organization slug. | |
| from | No | Absolute start time (inclusive, ISO 8601). Overrides `since`. Must be earlier than `to`. | |
| limit | No | Maximum traces to return (default: 20, max: 100). | |
| since | No | Lookback window as relative duration (default: "1h"). Examples: "30m", "2h", "1d". | |
| traceId | No | A trace ID from search results: returns that trace instead of searching. | |
| traceql | No | Raw TraceQL, e.g. `{ resource.gvc = "prod" && span.http.url =~ ".*/checkout.*" }`. REPLACES the structured params, so it must embed every filter. | |
| location | No | Filter traces to one location (e.g., "aws-us-east-1"). | |
| workload | No | Filter traces to one workload (matches the `resource.workload` span attribute). | |
| requestId | No | Only the trace of this request: the x-request-id in access and request logs. | |
| errorsOnly | No | Only return traces containing at least one error span. | |
| httpMethod | No | Only traces with a request of this HTTP method, e.g. "POST". | |
| minDuration | No | Only return traces slower than this total duration (e.g., "500ms", "2s") — the slow-request finder. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| data | No | The full result. Read this, not only the summary. | |
| details | No | ||
| summary | Yes | ||
| nextSteps | No |