Skip to content

Client functions

DatadogApmClient talks to the local Datadog Agent: its trace intake (GET /info on port 8126) for health, ping and version. It also starts tracing with the client's settings and gives access to the Datadog spans query API. The Agent has no authentication, so the client needs no credentials; apiKey and appKey are used only by spans.

Function Description
DatadogApmClient(config) / fromEnv() build a client from a DatadogApmConfig or from the environment (Configuration)
health() GET /info: healthy=true, status ok, details version, git_commit; unreachable on network errors, unhealthy on HTTP errors. Only CANCELLED and CONFIG are raised
ping() round trip to the Agent (GET /info), returns the latency (TypeScript/Python: ms, other languages: a duration)
serverVersion() the Agent version (7.85.4); UNSUPPORTED when /info has none
agentInfo() the /info document: version, git_commit, endpoints, config
initTracing(config) initTracing with the client's config as defaults (Agent host, OTLP endpoint and protocol, service, env, version, tags, TLS); close() shuts the handle down
spans the DatadogSpansQuery, created on first use and closed by close(); CONFIG without apiKey and appKey
close() idempotent: flushes and shuts down the tracing started through the client, then releases connections. Every later call raises CANCELLED
import { DatadogApmClient } from "@grow-codes/datadog-apm";

const client = DatadogApmClient.fromEnv({ serviceName: "checkout" });
const health = await client.health();          // { healthy, status, details }
console.log(await client.ping(), "ms", await client.serverVersion());
console.log((await client.agentInfo()).endpoints);
const tracing = client.initTracing({ environment: "prod" });
if (client.config.hasQueryCredentials) await client.spans.ping();
await client.close();                           // flushes `tracing`
use grow_datadog_apm::{DatadogApmClient, tracing::TracingConfig};

let client = DatadogApmClient::from_env()?;
let health = client.health().await?;
println!("{:?} {}", client.ping().await?, client.server_version().await?);
println!("{:?}", client.agent_info().await?.endpoints);
let tracing = client.init_tracing(TracingConfig::new("checkout").with_environment("prod"))?;
if let Ok(spans) = client.spans() {
    spans.ping().await?;
}
client.close().await; // flushes `tracing`

The blocking feature adds grow_datadog_apm::blocking::DatadogApmClient with health, ping, server_version and agent_info.

client, err := datadogapm.NewClientFromEnv()
if err != nil {
    return err
}
defer client.Close() // flushes the tracing below
health, _ := client.Health(ctx)
latency, err := client.Ping(ctx)
version, err := client.ServerVersion(ctx)
info, err := client.AgentInfo(ctx) // info.Endpoints, info.Config
tracing, err := client.InitTracing(ctx, datadogapm.TracingConfig{ServiceName: "checkout", Environment: "prod"})
if spans, err := client.Spans(); err == nil {
    _, _ = spans.Ping(ctx)
}
from grow_datadog_apm import DatadogApmClient

with DatadogApmClient.from_env(service_name="checkout") as client:
    health = client.health()
    print(client.ping(), "ms", client.server_version(), client.agent_info().endpoints)
    tracing = client.init_tracing(environment="prod")
    if client.config.has_query_credentials:
        client.spans.ping()
# close() flushed `tracing`

AsyncDatadogApmClient has the same methods (await client.health(), await client.aclose(), client.spans is an AsyncDatadogSpansQuery).

try (DatadogApmClient client = DatadogApmClient.fromEnv()) {
    HealthStatus health = client.health();
    System.out.println(client.ping().toMillis() + " ms " + client.serverVersion());
    System.out.println(client.agentInfo().endpoints());
    DatadogTracingHandle tracing =
        client.initTracing(TracingConfig.builder("checkout").environment("prod").build());
    if (client.config().hasQueryCredentials()) {
        client.spans().ping();
    }
} // close() flushes `tracing`

Every call has an …Async variant returning a CompletableFuture (healthAsync(), pingAsync(), serverVersionAsync(), agentInfoAsync()).

Errors

Situation Code
Agent not reachable health() → healthy=false, unreachable; other calls UNAVAILABLE (retried)
/info answers 404 (not a Datadog Agent trace intake) health() → unhealthy; other calls NOT_FOUND
no version in /info serverVersion() → UNSUPPORTED
spans without apiKey / appKey CONFIG naming DD_API_KEY / DD_APP_KEY
any call after close() CANCELLED ("client is closed")