Trace queries¶
ZipkinQueryClient reads traces back from Zipkin's v2 query API (port 9411). It offers the
native functions (getTraceSpans, getTraces, getTraceMany, listServices, listSpans,
listRemoteServices, getDependencies, autocompleteKeys, autocompleteValues) and the
category interface TraceQueryClient on top of them (getTrace, searchTraces,
listOperations, getDependencies, waitForTrace) with the normalized model
Trace { traceId, spans[] } / Span { traceId, spanId, parentSpanId, name, kind, serviceName,
startMicros, endMicros, durationMicros, status, attributes, events, links }.
Every call is a GET, retried on 5xx, 429 and network errors. Zipkin answers errors as plain text;
the text is kept in the error message (redacted). Invalid filters fail with VALIDATION before
a request is made.
getTraceSpans / getTrace¶
GET /api/v2/trace/{traceId}. getTraceSpans returns the stored spans (native model);
getTrace the normalized Trace (64-bit ids left-padded to 32 characters, spans sorted, Zipkin
kind lower-cased, tags → attributes, annotations → events, the error tag → status
error). Both return null / None / nil / Optional.empty() when the trace does not exist
(404). The id is lower-cased; anything but 16 or 32 hex characters is a VALIDATION error.
getTraces¶
GET /api/v2/traces: traces as stored, newest first, one span list per trace; no match → [].
Filters: serviceName, remoteServiceName, spanName, annotationQuery (raw Zipkin syntax),
tags (exact key=value), annotations (bare terms: a tag key or an annotation value),
minDuration / maxDuration (µs; max needs min), endTs (default now), lookback (default the
server's 24 h) and limit (default the server's 10). annotationQuery, tags and annotations
are joined with and (Zipkin knows AND only). A term whose key or value contains and (or a
key with =) cannot be expressed in Zipkin's syntax: it is matched client-side after the query,
so fewer than limit traces may come back.
use grow_zipkin::ZipkinTraceQuery;
let traces = query
.get_traces(
&ZipkinTraceQuery::service("frontend")
.span_name("get /orders")
.tag("http.method", "GET")
.annotation("error")
.duration(Some(Duration::from_millis(100)), None)
.window(SystemTime::now(), Duration::from_secs(900))
.limit(5),
)
.await?;
buildAnnotationQuery¶
Builds an annotationQuery string from tags and bare terms (http.method=GET and error); empty
when both are empty. A term Zipkin cannot express is a VALIDATION error. Tag order follows the
map (sorted in Go and Rust).
getTraceMany¶
GET /api/v2/traceMany?traceIds=…. Ids are lower-cased and de-duplicated (a 16-character id
equals its zero-padded 32-character form). An empty list returns [] without a request, one id
uses getTraceSpans, more go in chunks of 100 ids (longer URLs get HTTP 414 from Zipkin).
Missing traces are omitted; the result follows the request order.
searchTraces¶
The category search, mapped to getTraces: service → serviceName, operation → spanName,
tags → exact tag terms, durations in µs, end (default now) → endTs, end - start →
lookback — the last hour when start is not set (the same default in every tracing package
of Grow Codes), limit default 20. Returns one TraceSummary { traceId, rootServiceName, rootName,
startMicros, durationMicros, spanCount } per trace (root = the span without a parent, else the
earliest).
listServices / listSpans / listOperations / listRemoteServices¶
GET /api/v2/services, /api/v2/spans?serviceName= and /api/v2/remoteServices?serviceName=,
sorted. Names are lower-case (Zipkin lower-cases them on ingest); the service name is matched
case-insensitively. An unknown service returns []; an empty service name is a VALIDATION
error. listOperations is the category alias of listSpans.
getDependencies¶
GET /api/v2/dependencies?endTs=&lookback=: service dependency edges sorted by parent and child.
The Zipkin link keeps errorCount (0 when Zipkin omits it). The window is either the category
range (start / end) or Zipkin's native endTs + lookback; without a start or lookback the
server default (24 h) applies. In-memory storage computes edges on read; persistent backends need
the zipkin-dependencies job, so [] is normal
there. Edges come from CLIENT → SERVER span pairs and from CLIENT/PRODUCER spans with a remote
service name.
autocompleteKeys / autocompleteValues¶
GET /api/v2/autocompleteKeys returns the server's AUTOCOMPLETE_KEYS in configured order ([]
when unset — the Grow stack template sets none). GET /api/v2/autocompleteValues?key= returns
the sorted distinct values of one key ([] for a key outside the allowlist).
waitForTrace¶
Polls getTrace until the trace has at least minSpans spans (default 1) or the timeout
(default 30 s) passes (TIMEOUT). A test helper; with in-memory storage traces are queryable
right after the report.