Class SkyWalkingClient

java.lang.Object
codes.grow.packages.skywalking.SkyWalkingClient
All Implemented Interfaces:
AutoCloseable

public final class SkyWalkingClient extends Object implements AutoCloseable
Client for Apache SkyWalking OAP.

Implements SPEC section 2.4 plus the SkyWalking modules: query() (GraphQL query API), traces() (SPEC TraceQueryClient), logs() (SPEC LogQueryClient), logClient(codes.grow.packages.skywalking.core.HttpTransport, codes.grow.packages.skywalking.SkyWalkingLogClientOptions, boolean) (native log sender) and initTracing(codes.grow.packages.skywalking.tracing.TracingConfig) (OTLP/gRPC tracing). Thread-safe; create one per OAP and close it when done.


 try (SkyWalkingClient client = SkyWalkingClient.fromEnv()) {
   System.out.println(client.serverVersion());
   client.query().listServices().forEach(s -> System.out.println(s.name()));
 }
 

Every I/O method has a blocking form and an …Async form returning CompletableFuture.

  • Method Details

    • create

      public static SkyWalkingClient create(SkyWalkingConfig config)
      Creates a client.
      Parameters:
      config - validated configuration
      Returns:
      a new client
      Throws:
      ConfigException - when TLS or proxy settings are invalid
    • fromEnv

      public static SkyWalkingClient fromEnv()
      Creates a client from the SDK and vendor environment variables.
      Returns:
      a new client
    • builder

      public static SkyWalkingClient.Builder builder()
      Starts a client builder.
      Returns:
      a new builder
    • createLogClient

      public static BatchingLogClient createLogClient(SkyWalkingConfig config, SkyWalkingLogClientOptions options)
      A standalone BatchingLogClient that sends native logs to POST /v3/logs (owns its connections; close() flushes and releases them).
      Parameters:
      config - configuration
      options - service name, instance, resource and batch settings
      Returns:
      the log client
    • config

      public SkyWalkingConfig config()
      Returns the configuration.
      Returns:
      the configuration
    • transport

      public HttpTransport transport()
      Returns the HTTP transport, for service modules built on this client.
      Returns:
      the transport
    • query

      public SkyWalkingQueryClient query()
      The GraphQL query API: services, endpoints, instances, native traces, logs, topology.
      Returns:
      the query client
    • traces

      public SkyWalkingTraceQueryClient traces()
      SPEC TraceQueryClient (Zipkin store for OTLP spans, native store for agents) with the configured SkyWalkingConfig.traceBackend().
      Returns:
      the trace query client
    • logs

      public SkyWalkingLogQueryClient logs()
      SPEC LogQueryClient.
      Returns:
      the log query client
    • register

      public void register(AutoCloseable resource)
      Registers a resource closed with the client.
      Parameters:
      resource - the resource
    • health

      public HealthStatus health()
      Liveness: GET /healthcheck (OAP health checker, SW_HEALTH_CHECKER=default): 2xx → ok, other statuses → unhealthy. Without the health checker (404/405) falls back to GraphQL checkHealth (score 0 = ok). Never throws for an unhealthy or unreachable service (only CancelledException and ConfigException).
      Returns:
      the health status
    • healthAsync

      public CompletableFuture<HealthStatus> healthAsync()
      Asynchronous health().
      Returns:
      a future with the health status
    • ping

      public Duration ping()
      Timed GraphQL round trip (getTimeInfo; also caches the OAP time zone). OAP has no query authentication: an authentication error only comes from a gateway in front of it.
      Returns:
      the latency
    • pingAsync

      public CompletableFuture<Duration> pingAsync()
      Asynchronous ping().
      Returns:
      a future with the latency
    • serverVersion

      public String serverVersion()
      The OAP version from GraphQL {version}, for example 10.4.0-b272da3.
      Returns:
      the version string
      Throws:
      UnsupportedException - when the server reports none
    • serverVersionAsync

      public CompletableFuture<String> serverVersionAsync()
      Asynchronous serverVersion().
      Returns:
      a future with the version
    • graphql

      public GraphQLResponse graphql(String query, Map<String,?> variables)
      Raw GraphQL (same as query().graphql).
      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
    • logClient

      public BatchingLogClient logClient(SkyWalkingLogClientOptions options)
      A BatchingLogClient that sends native logs (POST /v3/logs) over this client's connections. close() flushes and closes it.
      Parameters:
      options - service name, instance, resource and batch settings
      Returns:
      the log client
    • logClient

      public BatchingLogClient logClient(String serviceName)
      A log client for one service with default batching.
      Parameters:
      serviceName - service.name of the records
      Returns:
      the log client
    • initTracing

      public TracingHandle initTracing(TracingConfig tracing)
      SkyWalkingTracing.initTracing(TracingConfig, SkyWalkingConfig) with this client's configuration (OTLP endpoint, protocol, headers, token, TLS). close() shuts the handle down.
      Parameters:
      tracing - tracing config
      Returns:
      the handle
    • isClosed

      public boolean isClosed()
      Returns whether close() was called.
      Returns:
      true once closed
    • close

      public void close()
      Flushes and closes log clients and tracing handles created here, then releases the connections. Idempotent.
      Specified by:
      close in interface AutoCloseable
    • toString

      public String toString()
      Overrides:
      toString in class Object