Quickstart¶
Point the SDK at a Datadog Agent with the OTLP receiver turned on, check that it is healthy, send a
trace with log-correlation fields and — with an API key and an application key — read it back from
Datadog. Configuration comes from the environment (DD_*, GROW_DATADOG_APM_*, see
Configuration) or from code.
export DD_AGENT_HOST=127.0.0.1 DD_SERVICE=checkout DD_ENV=dev
# the Agent: DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT=0.0.0.0:4318
# optional, for the query API (never commit real keys):
# export DD_API_KEY=... DD_APP_KEY=... DD_SITE=datadoghq.eu
1. Check the Agent¶
import { DatadogApmClient } from "@grow-codes/datadog-apm";
const client = DatadogApmClient.fromEnv();
try {
const health = await client.health();
console.log("healthy:", health.healthy, health.status);
console.log("ping:", await client.ping(), "ms");
console.log("server version:", await client.serverVersion());
} finally {
await client.close();
}
use grow_datadog_apm::DatadogApmClient;
#[tokio::main]
async fn main() -> grow_datadog_apm::Result<()> {
let client = DatadogApmClient::from_env()?;
let health = client.health().await?;
println!("healthy: {} {}", health.healthy, health.status);
println!("ping: {:?}", client.ping().await?);
println!("server version: {}", client.server_version().await?);
client.close().await;
Ok(())
}
package main
import (
"context"
"fmt"
"log"
datadogapm "github.com/grow-codes-packages/datadog-apm/go"
)
func main() {
ctx := context.Background()
client, err := datadogapm.NewClientFromEnv()
if err != nil {
log.Fatal(err)
}
defer client.Close()
health, err := client.Health(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println("healthy:", health.Healthy, health.Status)
latency, err := client.Ping(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println("ping:", latency)
version, err := client.ServerVersion(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println("server version:", version)
}
from grow_datadog_apm import DatadogApmClient
with DatadogApmClient.from_env() as client:
health = client.health()
print("healthy:", health.healthy, health.status)
print("ping:", client.ping(), "ms")
print("server version:", client.server_version())
Async code uses AsyncDatadogApmClient with the same methods:
import codes.grow.packages.datadogapm.DatadogApmClient;
import codes.grow.packages.datadogapm.core.HealthStatus;
public final class Quickstart {
public static void main(String[] args) {
try (DatadogApmClient client = DatadogApmClient.fromEnv()) {
HealthStatus health = client.health();
System.out.println("healthy: " + health.healthy() + " " + health.status());
System.out.println("ping: " + client.ping().toMillis() + " ms");
System.out.println("server version: " + client.serverVersion());
}
}
}
2. Send a trace and read it back¶
import { DatadogApmClient, datadogLogFields, withSpan } from "@grow-codes/datadog-apm";
const client = DatadogApmClient.fromEnv();
try {
console.log((await client.health()).healthy, await client.serverVersion());
const tracing = client.initTracing({ serviceVersion: "1.4.0" });
const traceId = await withSpan("place-order", async (span) => {
console.log(JSON.stringify({ msg: "order placed", ...datadogLogFields() }));
return span.spanContext().traceId;
});
await tracing.forceFlush();
if (client.config.hasQueryCredentials) {
const trace = await client.spans.waitForTrace(traceId, { timeoutMs: 120_000 });
console.log(trace.spans.map((s) => s.name));
}
} finally {
await client.close(); // flushes and shuts down the tracing it started
}
use grow_datadog_apm::tracing::{current_trace_id, with_span, SpanOptions, TraceQueryClient as _, TracingConfig};
use grow_datadog_apm::{datadog_log_fields, DatadogApmClient};
#[tokio::main]
async fn main() -> grow_datadog_apm::Result<()> {
let client = DatadogApmClient::from_env()?;
println!("{} {}", client.health().await?.healthy, client.server_version().await?);
let tracing = client.init_tracing(TracingConfig::new("checkout").with_service_version("1.4.0"))?;
let trace_id = with_span("place-order", SpanOptions::default(), async {
println!("{:?}", datadog_log_fields(Default::default()));
Ok::<_, grow_datadog_apm::Error>(current_trace_id().unwrap_or_default())
})
.await?;
tracing.force_flush(None).await?;
if let Ok(spans) = client.spans() {
let trace = spans.wait_for_trace(&trace_id, Default::default()).await?;
println!("{} spans", trace.spans.len());
}
client.close().await; // flushes and shuts down the tracing it started
Ok(())
}
package main
import (
"context"
"fmt"
"log"
"log/slog"
"time"
datadogapm "github.com/grow-codes-packages/datadog-apm/go"
)
func main() {
ctx := context.Background()
client, err := datadogapm.NewClientFromEnv()
if err != nil {
log.Fatal(err)
}
defer client.Close() // flushes and shuts down the tracing it started
health, _ := client.Health(ctx)
fmt.Println(health.Healthy)
tracing, err := client.InitTracing(ctx, datadogapm.TracingConfig{ServiceVersion: "1.4.0"})
if err != nil {
log.Fatal(err)
}
traceID, _ := datadogapm.WithSpan(ctx, "place-order", func(ctx context.Context) (string, error) {
slog.InfoContext(ctx, "order placed", "dd", datadogapm.DatadogLogFields(ctx, datadogapm.DatadogLogFieldsOptions{}))
id, _ := datadogapm.CurrentTraceID(ctx)
return id, nil
})
_ = tracing.ForceFlush(ctx)
if spans, err := client.Spans(); err == nil {
trace, err := spans.WaitForTrace(ctx, traceID, datadogapm.WaitForTraceOptions{Timeout: 2 * time.Minute})
if err == nil {
fmt.Println(len(trace.Spans), "spans")
}
}
}
from grow_datadog_apm import DatadogApmClient, current_trace_id, datadog_log_fields, with_span
with DatadogApmClient.from_env() as client: # close() flushes the tracing it started
print(client.health().healthy, client.server_version())
tracing = client.init_tracing(service_version="1.4.0")
with with_span("place-order"):
print({"msg": "order placed", **datadog_log_fields()})
trace_id = current_trace_id()
tracing.force_flush()
if client.config.has_query_credentials:
trace = client.spans.wait_for_trace(trace_id, timeout_s=120)
print([s.name for s in trace.spans])
import codes.grow.packages.datadogapm.DatadogApmClient;
import codes.grow.packages.datadogapm.DatadogLogCorrelation;
import codes.grow.packages.datadogapm.DatadogTracingHandle;
import codes.grow.packages.datadogapm.tracing.Spans;
import codes.grow.packages.datadogapm.tracing.query.Trace;
try (DatadogApmClient client = DatadogApmClient.fromEnv()) { // close() flushes the tracing it started
System.out.println(client.health().healthy() + " " + client.serverVersion());
DatadogTracingHandle tracing = client.initTracing();
String traceId = Spans.withSpan("place-order", () -> {
System.out.println(DatadogLogCorrelation.datadogLogFields()); // merge into your MDC
return Spans.currentTraceId().orElseThrow();
});
tracing.forceFlush();
if (client.config().hasQueryCredentials()) {
Trace trace = client.spans().waitForTrace(traceId);
System.out.println(trace.spans().size() + " spans");
}
}
Next steps¶
- Tracing setup: protocol, propagators, error attributes, unified service tagging.
- Propagation and ids:
x-datadog-*headers, id conversion, log correlation. - Spans query: search, aggregate and read traces from Datadog.
- Configuration: timeouts, retries, TLS, proxy, environment variables.
- Error handling: error codes and retries.