Query API (GraphQL)¶
SkyWalkingQueryClient (client.query) wraps OAP's GraphQL query protocol on port 12800: services,
endpoints, instances, native traces, logs and topology, plus the raw graphql call. It reads what
native sources store — SkyWalking agents, native segments and logs (/v3/segments,
/v3/logs) and OTLP logs. OTLP spans are stored in OAP's Zipkin model and are read with
Trace queries instead.
Common rules:
- Time windows (
range): default the last hour up to now, stepMINUTE, formatted in the OAP time zone (read once withgetTimeInfoand cached). - Ids of real services are derived without a lookup: service
base64(name).1, instance and endpoint<serviceId>_base64(name)(helpersserviceId/instanceId/endpointId, GoServiceID/InstanceID/EndpointID). - Native trace ids are opaque strings (
<hex>.<n>.<ms>) and are kept verbatim. - Missing required arguments and invalid paging are
VALIDATIONerrors before any request. GraphQL resolver errors becomeVALIDATION(UNSUPPORTEDwhen OAP reports anUnsupportedOperationException). - Metadata (services, instances, endpoints) appears about 30–40 s after the first data: OAP flushes its metadata index periodically.
listServices¶
GraphQL listServices(layer). layer omitted / null = all layers; an unknown layer returns an
empty list. OAP has no time filter for services, so range is accepted for symmetry and ignored
(Go omits the parameter). Services that only sent OTLP spans are not listed here; use
client.traces.listServices().
findService¶
GraphQL findService(serviceName); null / None / nil / Optional.empty() when unknown.
listEndpoints¶
GraphQL findEndpoint(keyword, serviceId, limit) (default limit 100). keyword is a tokenised
match: downstream finds /native/downstream, down does not. No duration is sent (OAP 10.4
with BanyanDB returns nothing when one is set).
listInstances¶
GraphQL listInstances(duration, serviceId): instances active in range (default last hour).
queryTraces¶
GraphQL queryTraces(condition) — whole native traces (all segments), the V2 trace query. Filters:
service, instance and endpoint (both need service), traceId, traceState
(ALL default, SUCCESS, ERROR), minDuration/maxDuration in ms, tags (only keys in the
server's SW_SEARCHABLE_TAG_KEYS can match), range (omitted when only traceId is given),
paging (page 1, size 20 by default; size ≤ 10 000) and order (BY_START_TIME default,
BY_DURATION). The legacy queryBasicTraces is not used: it is unsupported on BanyanDB.
getTrace¶
GraphQL queryTrace(traceId): one native trace with every span (segment id, span id, parent span
id, refs, tags, logs, component, layer, peer, error flag). null when unknown. OTLP trace ids are
never native — read them with client.traces.getTrace.
queryLogs¶
GraphQL queryLogs(condition). Filters: service, instance, endpoint (both need service),
traceId (native or 32-hex OpenTelemetry id; with segmentId and spanId for one span),
keywords / excludingKeywords, tags (keys must be in SW_SEARCHABLE_LOGS_TAG_KEYS), range
(default last hour; omitted when only traceId is given), paging and order (DES default,
ASC).
Keywords on BanyanDB
OAP with BanyanDB storage silently ignores keywordsOfContent. The SDK asks the server
(capabilities().logsByKeywords) and, when keyword search is not supported, filters the
returned page on the client (case-insensitive substring over the content). Use
logs.search for "find logs containing X" across pages.
listLogTagKeys¶
GraphQL queryLogTagAutocompleteKeys(duration): log tag keys seen in range, sorted.
topology¶
GraphQL getGlobalTopology(duration, layer) or, with service, getServiceTopology(serviceId,
duration). Nodes (with the virtual User node) and calls with detect points and components.
Native traffic only: OTLP spans create no topology edges.
timeInfo / capabilities¶
timeInfo is GraphQL getTimeInfo (OAP time zone and clock). capabilities probes
hasQueryTracesV2Support and supportQueryLogsByKeywords once and caches the answer
(queryTracesV2, logsByKeywords).
graphql¶
The raw call, see Client.