Trace queries¶
JaegerQueryClient reads traces back from Jaeger's query service (port 16686). It implements the
category interface TraceQueryClient and uses:
- the v3 HTTP API for traces, search, services and operations (
/api/v3/traces/{id},/api/v3/traces,/api/v3/trace-summaries,/api/v3/services,/api/v3/operations); - the legacy
/api/traces/{id}as a fallback forgetTracewhen the v3 route is missing (a plain-text404 page not found, or a proxy page that is not Jaeger's JSON envelope); - the legacy
/api/dependencies(Jaeger has no v3 HTTP dependencies route).
Get one from the client (it shares the client's connections and token) or build a standalone one from a config (it owns its connections; close it).
Results use the normalized model: Trace { traceId, spans[] } with spans sorted by start time,
Span { traceId, spanId, parentSpanId, name, kind, serviceName, startMicros, endMicros,
durationMicros, status, attributes, events, links }. Trace ids are 32 lower-case hex characters;
16-hex ids are left-padded; anything else raises ValidationError without a request.
getTrace / requireTrace¶
getTrace(traceId, {start?, end?, rawTraces?}) returns the trace or null when it does not exist
(Jaeger's JSON 404 envelope). The default lookup window is the last 7 days (the memory store
ignores it). requireTrace raises NotFoundError instead of returning null.
if let Some(trace) = client.query().get_trace("4bf92f3577b34da6a3ce929d0e0e4736").await? {
println!("{} spans", trace.spans.len());
}
let sure = client.query().require_trace(&trace_id).await?;
let raw = client
.query()
.get_trace_with(&trace_id, GetTraceOptions { raw_traces: true, ..Default::default() })
.await?;
tr, err := client.Query().GetTrace(ctx, "4bf92f3577b34da6a3ce929d0e0e4736")
if err != nil {
return err
}
if tr != nil {
fmt.Println(len(tr.Spans), "spans")
}
sure, err := client.Query().RequireTrace(ctx, traceID) // errors.Is(err, jaeger.ErrNotFound)
raw, err := client.Query().GetTraceWith(ctx, traceID, jaeger.GetTraceOptions{RawTraces: true})
findTraces / searchTraces¶
Both take the same filter: {service, operation, tags, minDurationMicros, maxDurationMicros,
start, end, limit}. Jaeger needs both time bounds, so the SDK always sends them (default: the last
hour); limit defaults to 20. tags match attributes on any span of the trace.
findTraces returns full traces (/api/v3/traces); searchTraces returns
TraceSummary { traceId, rootServiceName, rootName, startMicros, durationMicros, spanCount }
(/api/v3/trace-summaries). No match returns an empty list.
use grow_jaeger::tracing::TraceSearchQuery;
let mut q = TraceSearchQuery::service("checkout");
q.operation = Some("POST /orders".into());
q.tags.insert("http.response.status_code".into(), "500".into());
q.min_duration = Some(Duration::from_millis(1));
q.limit = 10;
let traces = client.query().find_traces(&q).await?;
let summaries = client.query().search_traces(&TraceSearchQuery::service("checkout")).await?;
traces, err := client.Query().FindTraces(ctx, jaeger.TraceSearchQuery{
Service: "checkout",
Operation: "POST /orders",
Tags: map[string]string{"http.response.status_code": "500"},
MinDuration: time.Millisecond,
Limit: 10,
})
summaries, err := client.Query().SearchTraces(ctx, jaeger.TraceSearchQuery{Service: "checkout"})
listServices¶
Service names with stored spans, sorted (/api/v3/services). The all-in-one also reports
itself as jaeger.
listOperations / getOperations¶
listOperations(service, {spanKind?}) returns operation names, sorted and de-duplicated across
span kinds; getOperations(service, {spanKind?}) returns {name, spanKind} pairs. The span kind
filter (server, client, producer, consumer, internal) is case-insensitive and always
sent lower-case (Jaeger silently returns nothing for SERVER). An empty service raises
ValidationError without a request; an unknown service returns an empty list.
names, err := client.Query().ListOperations(ctx, "checkout")
serverNames, err := client.Query().ListOperationsWith(ctx, "checkout", jaeger.ListOperationsOptions{SpanKind: jaeger.SpanKindServer})
server, err := client.Query().GetOperations(ctx, "checkout", jaeger.ListOperationsOptions{SpanKind: jaeger.SpanKindServer})
getDependencies¶
Service dependency edges DependencyLink { parent, child, callCount } from the legacy
/api/dependencies. Pass the category window (start/end, default the last 24 h) or Jaeger's
native endTs + lookback; an optional service keeps only edges that touch it. The memory
store derives edges on the fly; Cassandra, Elasticsearch and OpenSearch need the
spark-dependencies job, so an empty list is normal there.
waitForTrace¶
Test helper: polls getTrace until the trace has at least minSpans spans (defaults: timeout
30 s, interval 1 s, 1 span) and raises TimeoutError otherwise. An ingested span is queryable
about 200 ms after the export ack, so tests usually poll every 200–500 ms.
Errors¶
| Situation | Result |
|---|---|
| trace does not exist (JSON 404 envelope) | getTrace → null; requireTrace → NOT_FOUND |
| search without a match | empty list |
| route missing on the server (plain-text 404) | getTrace falls back to /api/traces/{id}; other calls → UNSUPPORTED |
| bad id, bad window, empty service, unknown span kind | VALIDATION, no request |
| 400 from Jaeger (e.g. bad duration) | VALIDATION with Jaeger's message |
| 401 / 403 from an auth proxy | AUTHENTICATION / PERMISSION_DENIED |
Error request ids fall back to Jaeger's traceresponse header.