Skip to content

Client

DatadogApmClient is the entry point. Create one per process (or per set of credentials), share it between threads/tasks and close it on shutdown. Service functions hang off the client (see Functions).

Function Returns Notes
constructor / create / new client validates the config (CONFIG error)
fromEnv() client config from GROW_DATADOG_APM_* and vendor variables
health() HealthStatus { healthy, status, details } Agent GET /info; never throws for an unhealthy or unreachable Agent, only for CANCELLED and CONFIG
ping() latency round trip to the Agent (GET /info); the Agent needs no credentials
serverVersion() version string Agent version from /info
agentInfo() /info document the Agent's endpoints, version and config
initTracing(config) tracing handle uses the client's settings as defaults; shut down by close()
spans DatadogSpansQuery Datadog API; CONFIG without apiKey + appKey
close() — idempotent; flushes and stops the tracing started through the client

status is ok, degraded, unhealthy, unreachable (network error) or the vendor's word.

Create, use and close

import { DatadogApmClient, DatadogApmConfig } from "@grow-codes/datadog-apm";

const client = new DatadogApmClient(new DatadogApmConfig({ url: "http://127.0.0.1:8126" }));
const health = await client.health();          // { healthy, status, details }
const latencyMs = await client.ping();         // number (ms)
const version = await client.serverVersion();  // string
await client.close();                          // safe to call twice

// Cancellation and per-call deadline: every I/O method accepts { signal }
const status = await client.health({ signal: AbortSignal.timeout(2_000) });
use grow_datadog_apm::{DatadogApmClient, DatadogApmConfig};

let config = DatadogApmConfig::builder().url("http://127.0.0.1:8126").build()?;
let client = DatadogApmClient::new(config)?;
let health = client.health().await?;          // HealthStatus
let latency = client.ping().await?;           // Duration
let version = client.server_version().await?; // String
client.close().await;                         // safe to call twice

// Cancellation: drop the future, e.g. with a deadline
let status = tokio::time::timeout(std::time::Duration::from_secs(2), client.health()).await;

Without an async runtime, enable the blocking feature:

let client = grow_datadog_apm::blocking::DatadogApmClient::from_env()?;
let health = client.health()?;
client, err := datadogapm.NewClient(datadogapm.Config{
    CommonConfig: datadogapm.CommonConfig{URL: "http://127.0.0.1:8126"},
})
if err != nil {
    return err
}
defer client.Close() // safe to call twice

health, err := client.Health(ctx)         // HealthStatus
latency, err := client.Ping(ctx)          // time.Duration
version, err := client.ServerVersion(ctx) // string

// Cancellation and deadlines come from ctx
ctx2, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
health, err = client.Health(ctx2)
from grow_datadog_apm import CancelToken, DatadogApmClient, DatadogApmConfig

with DatadogApmClient(DatadogApmConfig(url="http://127.0.0.1:8126")) as client:
    health = client.health()           # HealthStatus
    latency_ms = client.ping()         # float (ms)
    version = client.server_version()  # str

    # Cancel from another thread
    token = CancelToken()
    health = client.health(cancel=token)
# close() ran; calling it again is safe

AsyncDatadogApmClient has the same methods as coroutines (await client.health(), await client.aclose(), async with), and honours task cancellation.

DatadogApmConfig config = DatadogApmConfig.builder().url("http://127.0.0.1:8126").build();
try (DatadogApmClient client = DatadogApmClient.create(config)) {
  HealthStatus health = client.health();
  Duration latency = client.ping();
  String version = client.serverVersion();

  // Async variants return CompletableFuture; cancel(true) cancels the request
  CompletableFuture<HealthStatus> pending = client.healthAsync();
  pending.orTimeout(2, TimeUnit.SECONDS).join();
} // close() is idempotent

Lifecycle rules

  • The client is safe for concurrent use. Reuse it: it keeps a connection pool.
  • close() flushes queued work (for example log batches) within the configured deadline and is safe to call more than once. Any call on a closed client fails with CANCELLED ("<operation>: client is closed").
  • Each language also offers its idiomatic scope: TypeScript try/finally, Rust close().await (plus best-effort Drop), Go defer client.Close(), Python with/async with, Java try-with-resources.