Propagation, ids and log correlation¶
Datadog tracers (dd-trace) and OpenTelemetry describe the same trace differently: Datadog uses
the low 64 bits of the trace id as an unsigned decimal plus the high 64 bits as hex in the
_dd.p.tid tag, OpenTelemetry uses 32 hex characters. The functions on this page translate between
the two, so traces cross services that use either kind of tracer and logs link to traces.
All behaviour was checked byte for byte against Datadog's own Python tracer (ddtrace 4.16.5) used as a reference, and end to end through the real Agent. No ddtrace code is used.
DatadogPropagator¶
An OpenTelemetry TextMapPropagator for the Datadog headers. initTracing installs it by default
(name datadog, before W3C tracecontext and baggage).
| Header | Inject | Extract |
|---|---|---|
x-datadog-trace-id |
low 64 bits of the trace id, decimal | required, digits only |
x-datadog-parent-id |
span id, decimal | required, digits only |
x-datadog-sampling-priority |
1 sampled, 0 not sampled |
> 0 = sampled |
x-datadog-tags |
_dd.p.tid=<16 hex> when the high 64 bits are not zero |
_dd.p.tid restores the 128-bit id |
x-datadog-origin |
— | kept in the trace state |
Conflict rules with W3C tracecontext (same as ddtrace): Datadog wins for the trace id; a W3C
context with another trace id becomes a terminated_context span link; with the same trace id the
W3C parent id wins.
| Function | Description |
|---|---|
DatadogPropagator |
the propagator (TypeScript new DatadogPropagator(), Rust DatadogPropagator::new(), Go datadogapm.DatadogPropagator{}, Python DatadogPropagator(), Java DatadogPropagator.getInstance()) |
extractDatadogContext(carrier) |
the remote SpanContext in the Datadog headers, or none |
terminatedContext(ctx) |
the W3C context that lost during extract, if any |
terminatedContextLinks(ctx) |
that context as a span link (reason=terminated_context) for the first server span |
DATADOG_*_HEADER constants |
the header names (Go DatadogTraceIDHeader, …; Java DatadogPropagator.TRACE_ID_HEADER, …) |
import { inject, extract, extractDatadogContext, terminatedContextLinks } from "@grow-codes/datadog-apm";
import { defaultTextMapGetter } from "@opentelemetry/api";
const headers: Record<string, string> = {};
inject(headers); // x-datadog-*, traceparent, baggage
const parent = extract(incoming);
const sc = extractDatadogContext(incoming, defaultTextMapGetter);
const links = terminatedContextLinks(parent);
use std::collections::HashMap;
use grow_datadog_apm::{extract_datadog_context, terminated_context_links, tracing};
let mut headers = HashMap::new();
tracing::inject(&mut headers);
let parent = tracing::extract(&incoming);
let sc = extract_datadog_context(&incoming);
let links = terminated_context_links(&parent);
Trace and span ids¶
| Function | Description |
|---|---|
toDatadogTraceId(hex) |
{low64Decimal, high64Hex, is128Bit} from an OpenTelemetry trace id (1–32 hex, left-padded) |
fromDatadogTraceId(low64Decimal, high64Hex?) |
the 32-hex OpenTelemetry trace id |
toDatadogSpanId(hex) / fromDatadogSpanId(decimal) |
16 hex ↔ unsigned decimal |
datadogTraceIdString(hex) |
the dd.trace_id form: 32 hex for a 128-bit id, decimal low 64 bits for a 64-bit id |
normalizeDatadogTraceId(value) / normalizeDatadogSpanId(value) |
any id Datadog returns → 32 / 16 hex (span id: none for 0 or empty) |
traceIdForPath(hex) |
the id for GET /api/v2/trace/{id}: Datadog reads an all-digit id as decimal, so such ids are sent as their decimal value |
Invalid ids, all-zero trace ids and values above 2^64 − 1 raise VALIDATION.
Mapping a Datadog span whose own span_id is missing or 0 also raises VALIDATION.
Log correlation¶
datadogLogFields() returns the fields Datadog uses to link logs to traces, in the same format as
the Datadog tracers' log injection: dd.trace_id (32 hex for a 128-bit id, decimal for a 64-bit
id), dd.span_id (decimal), dd.service, dd.env, dd.version. Service, env and version come
from the explicit options, else the active span's resource, else the defaults that the last
initTracing set (setDatadogLogDefaults sets them by hand, for spans from another tracer
provider). Without an active span only the service fields are returned. The generic
traceFields() ({trace_id, span_id} in hex) stays available.