Class DatadogLogsClient

java.lang.Object
codes.grow.packages.datadoglogs.DatadogLogsClient
All Implemented Interfaces:
AutoCloseable

public final class DatadogLogsClient extends Object implements AutoCloseable
Client for Datadog Log Management: API key checks, the logs intake (logClient(), exporter()) and the query API (query(), needs the application key).

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


 try (DatadogLogsClient client = DatadogLogsClient.fromEnv()) {
   DatadogLogClient logs = client.logClient();
   logs.logger("checkout").info("user signed in", Map.of("user", Map.of("id", 42)));
 } // close() flushes the log client
 
  • Field Details

  • Method Details

    • create

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

      public static DatadogLogsClient fromEnv()
      Creates a client from GROW_DATADOG_LOGS_*, DD_API_KEY, DD_SITE, …
      Returns:
      a new client
    • builder

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

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

      public HttpTransport transport()
      Returns the HTTP transport (base URL = the API host).
      Returns:
      the transport
    • register

      public void register(AutoCloseable resource)
      Registers a resource (log client, tail) closed with the client.
      Parameters:
      resource - the resource
      Throws:
      CancelledException - after close()
    • health

      public HealthStatus health()
      Reachability through GET /api/v1/validate (Datadog has no health endpoint): 2xx is healthy ok (details.apiKeyValid); 401/403 is unauthorized (not healthy); 429 degraded; other statuses unhealthy; network errors unreachable. Never throws except for cancellation and configuration errors.
      Returns:
      the health status
    • healthAsync

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

      public Duration ping()
      Validates the API key with GET /api/v1/validate and returns the latency.
      Returns:
      the latency
      Throws:
      AuthenticationException - when Datadog rejects the key (401/403)
      UnavailableException - when a 2xx answer has no {"valid": true}
    • pingAsync

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

      public boolean validateApiKey()
      Reports whether Datadog accepts the configured API key (GET /api/v1/validate): true for {"valid": true}, false for HTTP 403 or {"valid": false}. Never needs the application key.
      Returns:
      whether the key is valid
      Throws:
      UnavailableException - when a 2xx answer has no valid field
    • validateApiKeyAsync

      public CompletableFuture<Boolean> validateApiKeyAsync()
      Asynchronous validateApiKey().
      Returns:
      a future with the result
    • serverVersion

      public String serverVersion()
      Datadog is a SaaS without a version endpoint.
      Returns:
      never
      Throws:
      UnsupportedException - always
    • serverVersionAsync

      public CompletableFuture<String> serverVersionAsync()
      Asynchronous serverVersion(): always failed with UnsupportedException.
      Returns:
      a failed future
    • exporter

      public DatadogLogExporter exporter()
      Returns the intake exporter (Datadog limits). Most users call logClient() instead.
      Returns:
      the exporter
    • logClient

      public DatadogLogClient logClient()
      A batching log client with the default options.
      Returns:
      a new log client
    • logClient

      public DatadogLogClient logClient(BatchOptions batchOptions)
      A batching log client with the given batch options.
      Parameters:
      batchOptions - batch options (capped at 1000 records / 5 000 000 bytes per batch)
      Returns:
      a new log client
    • logClient

      public DatadogLogClient logClient(DatadogLogClient.Options options)
      A batching log client. The resource defaults to the configured service ( service.name), version (service.version), env ( deployment.environment) and hostname (host.name); options.resource() wins. close() flushes and closes every log client it created.
      Parameters:
      options - batching, resource, redaction and intake limits
      Returns:
      a new log client
      Throws:
      CancelledException - after close()
    • query

      public DatadogLogsQuery query()
      The query client (search, aggregate, indexes, tail).
      Returns:
      the query client
      Throws:
      ConfigException - without an application key
    • isClosed

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

      public void close()
      Flushes and closes every log client, stops running tails, then releases connections. Idempotent.
      Specified by:
      close in interface AutoCloseable
    • toString

      public String toString()
      Overrides:
      toString in class Object