Class TempoClient

java.lang.Object
codes.grow.packages.tempo.TempoClient
All Implemented Interfaces:
AutoCloseable

public final class TempoClient extends Object implements AutoCloseable
Client for Grafana Tempo's HTTP API (port 3200): health, ping, version and the query API through query(). Spans are sent with TempoTracing.initTracing(codes.grow.packages.tempo.TempoTracingConfig) (OTLP).

 try (TempoClient client = TempoClient.fromEnv()) {
   Optional<Trace> trace = client.query().getTrace(traceId);
 }
 

Implements SPEC section 2.4. Thread-safe; create one per endpoint and close it when done. Every I/O method has a blocking form and an …Async form returning CompletableFuture.

  • Method Details

    • create

      public static TempoClient create(TempoConfig config)
      Creates a client.
      Parameters:
      config - configuration
      Returns:
      a new client
      Throws:
      ConfigException - when the configuration, TLS or proxy settings are invalid
    • fromEnv

      public static TempoClient fromEnv()
      Creates a client from GROW_GRAFANA_TEMPO_*, then TEMPO_URL, TEMPO_TENANT_ID and the GROW_TEMPO_* aliases.
      Returns:
      a new client
    • builder

      public static TempoClient.Builder builder()
      Starts a client builder.
      Returns:
      a new builder
    • config

      public TempoConfig 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 TempoQueryClient query()
      Query API (getTrace, search, searchTags, traceQLMetrics, …) sharing this client.
      Returns:
      the query client
    • register

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

      public HealthStatus health()
      Readiness: GET /ready (no tenant needed). ready → healthy, status ok; HTTP 503 while Tempo starts (or any other answer) → unhealthy with details.reason; network errors → unreachable. Never throws for an unhealthy or unreachable service.
      Returns:
      the health status
      Throws:
      CancelledException - when interrupted or closed
    • healthAsync

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

      public Duration ping()
      Tenant-aware round trip: GET /api/v2/search/tags?scope=intrinsic. A multi-tenant Tempo without a tenant → AuthenticationException ("tenant required").
      Returns:
      the latency
      Throws:
      AuthenticationException - when the tenant is missing or a proxy rejects the credentials
    • pingAsync

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

      public String serverVersion()
      Server version ("3.1.1") from /api/status/buildinfo, falling back to the text of /status/version. A leading v is removed.
      Returns:
      the version string
      Throws:
      UnsupportedException - when the server reports none
    • serverVersionAsync

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

      public BuildInfo buildInfo()
      Build information (GET /api/status/buildinfo); same as query().buildInfo().
      Returns:
      build information
    • buildInfoAsync

      public CompletableFuture<BuildInfo> buildInfoAsync()
      Asynchronous buildInfo().
      Returns:
      future build information
    • echo

      public String echo()
      GET /api/echo → "echo"; same as query().echo().
      Returns:
      the echoed text
    • echoAsync

      public CompletableFuture<String> echoAsync()
      Asynchronous echo().
      Returns:
      future text
    • ready

      public boolean ready()
      GET /ready → true when ready, false while starting; throws on network errors. Same as query().ready().
      Returns:
      readiness
    • readyAsync

      public CompletableFuture<Boolean> readyAsync()
      Asynchronous ready().
      Returns:
      future readiness
    • isClosed

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

      public void close()
      Closes registered resources and releases connections; later calls fail with CancelledException. Idempotent.
      Specified by:
      close in interface AutoCloseable
    • toString

      public String toString()
      Overrides:
      toString in class Object