Class SkyWalkingQueryClient

java.lang.Object
codes.grow.packages.skywalking.SkyWalkingQueryClient

public final class SkyWalkingQueryClient extends Object
The SkyWalking GraphQL query API (POST /graphql on port 12800): services, endpoints, instances, native traces, logs, topology and raw GraphQL. Obtain it from SkyWalkingClient.query(). Services, instances and endpoints are given by name; the SDK derives the ids (SkyWalkingIds).

Every method has a blocking form and an …Async form returning CompletableFuture. Errors: HTTP 400 and resolver errors → ValidationException, an UnsupportedOperationException on the server → UnsupportedException, other statuses per SPEC section 2.1. Thread-safe.

  • Field Details

  • Method Details

    • graphql

      public GraphQLResponse graphql(String query, Map<String,?> variables)
      Raw GraphQL: returns data and errors (partial data possible). HTTP 400 (syntax or validation errors) throws ValidationException.
      Parameters:
      query - GraphQL document
      variables - variables (may be null)
      Returns:
      the response
    • graphql

      public GraphQLResponse graphql(String query)
      Raw GraphQL without variables.
      Parameters:
      query - GraphQL document
      Returns:
      the response
    • graphqlAsync

      public CompletableFuture<GraphQLResponse> graphqlAsync(String query, Map<String,?> variables)
      Asynchronous graphql(String, Map).
      Parameters:
      query - GraphQL document
      variables - variables (may be null)
      Returns:
      a future with the response
    • timeInfo

      public TimeInfo timeInfo()
      OAP clock and time zone (getTimeInfo); caches the time zone for query windows.
      Returns:
      the time info
    • timeInfoAsync

      public CompletableFuture<TimeInfo> timeInfoAsync()
      Asynchronous timeInfo().
      Returns:
      a future with the time info
    • capabilities

      public SkyWalkingCapabilities capabilities()
      Server features (hasQueryTracesV2Support, supportQueryLogsByKeywords), probed once and cached.
      Returns:
      the capabilities
    • capabilitiesAsync

      public CompletableFuture<SkyWalkingCapabilities> capabilitiesAsync()
      Asynchronous capabilities().
      Returns:
      a future with the capabilities
    • listServices

      public List<SkyWalkingService> listServices()
      Every service of every layer.
      Returns:
      the services
    • listServices

      public List<SkyWalkingService> listServices(String layer)
      Services of one layer (listServices(layer)).
      Parameters:
      layer - layer such as GENERAL; null = all layers; an unknown layer gives []
      Returns:
      the services
    • listServices

      public List<SkyWalkingService> listServices(String layer, TimeRange range)
      Services (listServices(layer)). OAP has no time filter for services, so range is accepted for API symmetry and ignored. Services that only sent OTLP traces are not listed (use SkyWalkingTraceQueryClient.listServices()); new services appear about 30 s after their first data.
      Parameters:
      layer - layer, or null for all layers
      range - ignored
      Returns:
      the services
    • listServicesAsync

      public CompletableFuture<List<SkyWalkingService>> listServicesAsync(String layer, TimeRange range)
      Parameters:
      layer - layer, or null for all layers
      range - ignored
      Returns:
      a future with the services
    • findService

      public Optional<SkyWalkingService> findService(String name)
      One service by name (findService).
      Parameters:
      name - service name
      Returns:
      the service, or empty when OAP does not know it
    • findServiceAsync

      public CompletableFuture<Optional<SkyWalkingService>> findServiceAsync(String name)
      Asynchronous findService(String).
      Parameters:
      name - service name
      Returns:
      a future with the service, or empty
    • listEndpoints

      public List<SkyWalkingEndpoint> listEndpoints(String service)
      Every endpoint of a service (at most 100).
      Parameters:
      service - service name
      Returns:
      the endpoints
    • listEndpoints

      public List<SkyWalkingEndpoint> listEndpoints(String service, String keyword)
      Endpoints of a service matching a keyword (at most 100).
      Parameters:
      service - service name
      keyword - keyword or null
      Returns:
      the endpoints
    • listEndpoints

      public List<SkyWalkingEndpoint> listEndpoints(String service, String keyword, int limit)
      Endpoints of a service (findEndpoint(keyword, serviceId, limit)). keyword is OAP's token match, not a substring match: downstream finds /native/downstream, down does not; null or empty lists all. No duration is sent (OAP 10.4 + BanyanDB returns nothing with one). Only native services have endpoints; OTLP spans create none.
      Parameters:
      service - service name
      keyword - keyword or null
      limit - maximum number of endpoints (positive)
      Returns:
      the endpoints
    • listEndpointsAsync

      public CompletableFuture<List<SkyWalkingEndpoint>> listEndpointsAsync(String service, String keyword, int limit)
      Parameters:
      service - service name
      keyword - keyword or null
      limit - maximum number of endpoints
      Returns:
      a future with the endpoints
    • listInstances

      public List<SkyWalkingInstance> listInstances(String service)
      Instances of a service active in the last hour.
      Parameters:
      service - service name
      Returns:
      the instances
    • listInstances

      public List<SkyWalkingInstance> listInstances(String service, TimeRange range)
      Instances of a service active in range (listInstances).
      Parameters:
      service - service name
      range - window, or null for the last hour
      Returns:
      the instances
    • listInstancesAsync

      public CompletableFuture<List<SkyWalkingInstance>> listInstancesAsync(String service, TimeRange range)
      Parameters:
      service - service name
      range - window, or null for the last hour
      Returns:
      a future with the instances
    • queryTraces

      public QueryTracesResult queryTraces(QueryTracesOptions options)
      Native traces (queryTraces(condition), whole traces). Durations in ms; tags must be searchable keys. Traces sent over OTLP are not stored here (use SkyWalkingClient.traces() with the zipkin backend). The legacy queryBasicTraces is not used (unsupported on BanyanDB).
      Parameters:
      options - filter
      Returns:
      one page of traces
    • queryTracesAsync

      public CompletableFuture<QueryTracesResult> queryTracesAsync(QueryTracesOptions options)
      Parameters:
      options - filter
      Returns:
      a future with one page of traces
    • getTrace

      public Optional<NativeTrace> getTrace(String traceId)
      One native trace (queryTrace(traceId)); the id is kept verbatim.
      Parameters:
      traceId - native trace id
      Returns:
      the trace, or empty when unknown (OTLP trace ids are never native)
    • getTraceAsync

      public CompletableFuture<Optional<NativeTrace>> getTraceAsync(String traceId)
      Asynchronous getTrace(String).
      Parameters:
      traceId - native trace id
      Returns:
      a future with the trace, or empty
    • queryLogs

      public QueryLogsResult queryLogs(QueryLogsOptions options)
      Logs (queryLogs(condition)). Either a window (default the last hour) or a trace id is sent; see QueryLogsOptions.keywords() for keyword handling on BanyanDB.
      Parameters:
      options - filter
      Returns:
      one page of logs
    • queryLogsAsync

      public CompletableFuture<QueryLogsResult> queryLogsAsync(QueryLogsOptions options)
      Parameters:
      options - filter
      Returns:
      a future with one page of logs
    • listLogTagKeys

      public List<String> listLogTagKeys()
      Log tag keys seen in the last hour (queryLogTagAutocompleteKeys), sorted.
      Returns:
      the keys
    • listLogTagKeys

      public List<String> listLogTagKeys(TimeRange range)
      Log tag keys seen in range (queryLogTagAutocompleteKeys), sorted.
      Parameters:
      range - window, or null for the last hour
      Returns:
      the keys
    • listLogTagKeysAsync

      public CompletableFuture<List<String>> listLogTagKeysAsync(TimeRange range)
      Parameters:
      range - window, or null for the last hour
      Returns:
      a future with the keys
    • topology

      public Topology topology()
      The global service topology of the last hour.
      Returns:
      the topology
    • topology

      public Topology topology(TimeRange range)
      The global service topology of range.
      Parameters:
      range - window, or null for the last hour
      Returns:
      the topology
    • topology

      public Topology topology(TimeRange range, TopologyOptions options)
      Service topology (getGlobalTopology(duration, layer), or getServiceTopology when TopologyOptions.service() is set). Native traffic only (OTLP spans create no edges); includes the virtual User node.
      Parameters:
      range - window, or null for the last hour
      options - service or layer filter
      Returns:
      the topology
      Throws:
      SkyWalkingException - on failure
    • topologyAsync

      public CompletableFuture<Topology> topologyAsync(TimeRange range, TopologyOptions options)
      Parameters:
      range - window, or null for the last hour
      options - service or layer filter
      Returns:
      a future with the topology