Query client¶
TempoQueryClient reads traces back from Tempo's HTTP API. Get it from client.query (it shares
the client's transport and tenant) or build an owned one from a config. It implements the shared
TraceQueryClient interface (getTrace, searchTraces, listServices, listOperations,
getDependencies, waitForTrace, see Tracing) and adds Tempo's own API.
Visibility delay
Trace by id is visible right after the export. Search, tags and metrics see new spans about 30 seconds after ingest (Tempo's live-store cut), so poll in tests.
getTrace¶
getTrace(traceId, {start, end}) → Trace or null / None / Optional.empty() / nil.
GET /api/v2/traces/{id}; when the v2 route itself is missing (404) the SDK falls back to the v1 routeGET /api/traces/{id}.- A trace that does not exist (or belongs to another tenant) is not an error: v2 answers
HTTP 200
{"trace":{}}, v1 answers 404, both become "no trace". - Ids may be upper case or shorter than 32 hex characters (left-padded). Ids in the answer are converted from base64 to lower-case hex; spans are sorted (parents first, then start time).
start/endnarrow the backend blocks that are searched; recent (live) data is returned anyway.- An invalid id →
VALIDATIONbefore any request.
search¶
search({traceql, start, end, limit, spss}) → {traces, metrics} (GET /api/search).
traceqlis a string or aTraceQLbuilder. Without a query (or a blank one) noqis sent and Tempo matches every trace.limit(traces, server default 20) andspss(spans per span set, server default 3) must be positive:0or a negative number is aVALIDATIONerror. Go uses the zero value for "unset", so there only negative numbers are rejected.- Each hit has
traceId(32 hex),rootServiceName,rootTraceName, start time, duration,spanSets(matched spans,matchedmay exceed the spans returned) and per-service stats. Span names in span sets are only present when the query selects them (| select(name)). - Invalid TraceQL →
VALIDATION(HTTP 400).
use grow_grafana_tempo::{SearchRequest, TraceQL};
let q = TraceQL::span([("resource.service.name", "api")]).and("status", "=", "error");
let res = client.query().search(&SearchRequest::from_traceql(&q)?.limit(20).spss(5)).await?;
for t in &res.traces {
println!("{} {:?}", t.trace_id, t.root_trace_name);
}
traceQL, err := tempo.TraceQL.Span(map[string]any{"resource.service.name": "api"}).
And("status", "=", "error").Build()
if err != nil {
return err
}
res, err := client.Query().Search(ctx, tempo.SearchRequest{TraceQL: traceQL, Limit: 20, SpansPerSpanSet: 5})
for _, t := range res.Traces {
fmt.Println(t.TraceID, t.RootTraceName, t.Duration)
}
searchTraces¶
searchTraces({service, operation, tags, minDuration, maxDuration, start, end, limit}) →
TraceSummary[] — the shared tracing search. The query becomes one TraceQL span set:
service → resource.service.name, operation → name, tags → unscoped attributes (.key),
min/max duration → trace:duration >= / <= (trace-level duration). limit defaults to 20.
Durations in the summaries have millisecond precision (Tempo's search API).
searchTags and searchTagValues¶
searchTags({scope, query, start, end}) → attribute names per scope
(GET /api/v2/search/tags), for example {"resource": ["service.name"], "span": ["http.route"]}.
Scopes: resource, span, intrinsic, event, link, instrumentation (none = all).
searchTagValues(tag, {query, start, end}) → TagValue {type, value} list
(GET /api/v2/search/tag/{tag}/values). tag is a TraceQL field (resource.service.name,
span.http.response.status_code, an intrinsic such as name or status, or a quoted name
span."my key"); it is URL-encoded as one path segment. Unscoped tags (service.name) →
VALIDATION.
Tempo ignores an invalid query on these endpoints and returns unfiltered values, so the SDK checks
the TraceQL on the client side first (VALIDATION).
use grow_grafana_tempo::{SearchTagValuesOptions, SearchTagsOptions, TagScope};
let tags = client.query().search_tags(&SearchTagsOptions::scope(TagScope::Span)).await?;
let values = client
.query()
.search_tag_values("span.http.route", &SearchTagValuesOptions::query(r#"{ resource.service.name = "api" }"#))
.await?;
listServices and listOperations¶
listServices() → service names (tag values of resource.service.name);
listOperations(service) → span names of that service (tag values of name, filtered by
{ resource.service.name = "<service>" }). TypeScript and Python also accept an optional time
range.
traceQLMetrics¶
traceQLMetrics(query, {start, end, since, step, exemplars}) → series with labels, samples and
exemplars (GET /api/metrics/query_range). query must end in a metrics function
(| rate(), | count_over_time(), | quantile_over_time(duration, .9), …). since is a relative
range (ignored when start is set), step the sample interval; both must be positive.
exemplars must be positive (Go: 0 = server default). Samples whose value is 0 (omitted by
Tempo) come back as 0.
waitForTrace¶
waitForTrace(traceId, {timeout, interval, minSpans}) polls getTrace until the trace exists with
at least minSpans spans (defaults: 30 s, 1 s, 1) and raises TIMEOUT otherwise. Meant for tests.
getDependencies¶
Tempo has no dependency-graph endpoint (its service-graph processor writes metrics to Prometheus
instead), so getDependencies always raises UNSUPPORTED in every language. It is covered by unit
tests only.