Trace queries¶
SkyWalkingTraceQueryClient (client.traces) implements the category interface
TraceQueryClient (getTrace, searchTraces, listServices, listOperations,
getDependencies, waitForTrace) with the normalized model Trace { traceId, spans[] } /
Span { traceId, spanId, parentSpanId, name, kind, serviceName, startMicros, endMicros,
durationMicros, status, attributes, events, links }.
OAP keeps traces in two stores:
| Store | Written by | Read through | Trace ids |
|---|---|---|---|
| Zipkin model | OTLP spans (what initTracing sends) |
Zipkin query API :9412/zipkin (SW_QUERY_ZIPKIN=default) |
32 hex (normalized) |
| Native model | SkyWalking agents, /v3/segments |
GraphQL | opaque <hex>.<n>.<ms>, kept verbatim |
SkyWalkingConfig.traceBackend (GROW_APACHE_SKYWALKING_TRACE_BACKEND) selects the store:
| Method | zipkin |
native |
auto (default) |
|---|---|---|---|
getTrace |
Zipkin | GraphQL queryTrace |
16/32-hex id → Zipkin, then GraphQL when not found; other ids → GraphQL |
searchTraces |
Zipkin /api/v2/traces |
GraphQL queryTraces |
Zipkin |
listServices, listOperations |
Zipkin | GraphQL | union of both, sorted |
getDependencies |
UNSUPPORTED |
native topology | native topology |
waitForTrace |
polls getTrace |
polls getTrace |
polls getTrace |
Rust, Go and Java also offer withBackend(...) / with_backend(...), a copy of the client that
reads another store; in TypeScript and Python set traceBackend / trace_backend in the config.
Native ids are kept verbatim (SPEC exception)
The SPEC model normalizes trace ids to 32 hex and span ids to 16 hex. Native SkyWalking ids are
not hex, so getTrace, searchTraces and waitForTrace keep them exactly as OAP returns them:
the trace id <hex>.<n>.<ms> and span ids "<segmentId>-<spanId>" (the parent is the same
segment's parent span, or the ref of the first span for cross-segment links). Hex ids from the
Zipkin store are normalized as usual. The generated sdk-kit trace models normalize ids, so each
language carries a service-side variant (see Compatibility).
getTrace¶
One trace, or null / None / nil / Optional.empty() when it does not exist. The Zipkin store
lower-cases names (OAP stores span names lower-cased), turns attributes into string tags and events
into annotations; the SDK maps them back (error tag and otel.status_* → status). A non-hex id
on the zipkin backend is a VALIDATION error (the OAP 400 text is kept in the message).
searchTraces¶
SPEC search → TraceSummary[] (traceId, rootServiceName, rootName, startMicros,
durationMicros, spanCount), default limit 20.
- Zipkin:
service→serviceName,operation→spanName(lower-cased),tags→annotationQueryk=v and …(keys must be in OAP'sSW_ZIPKIN_SEARCHABLE_TAG_KEYS), durations in µs,endTs=end(default now),lookback=end − startwhenstartis set. - Native:
queryTraceswithoperationas endpoint name (needsservice), durations rounded to ms, window default the last hour.
listServices / listOperations¶
Service names and the operation names of one service (Zipkin span names and/or native endpoint names), sorted and unique. New services appear about 30–40 s after their first data.
getDependencies¶
Service → service links from the native topology. callCount is always 0: the topology carries no
counts (they would need MQE metrics). OAP 10.4 does not implement Zipkin /dependencies (404), so
the zipkin backend raises UNSUPPORTED; OTLP spans create no topology edges.
waitForTrace¶
Test helper: polls getTrace until the trace has minSpans spans (default 1; timeout 30 s,
interval 1 s) and raises TIMEOUT otherwise. Native ids are used verbatim, hex ids are normalized.
OTLP spans become readable 5–15 s after export.