Connecting Logs and Traces

The idea in one sentence

A tracer already knows which span is active while your code handles a request, so log injection is simply the tracer handing that active trace_id (and span_id) to your logging library, so every log line written during that request carries the identifiers needed to find it again.

Without it: a log line with nowhere to go

2026-07-08T10:14:02Z ERROR Failed to charge card for order 48213

This line tells you something failed — it does not tell you which downstream call was slow, which service further down the chain actually produced the error, or what else happened during the same request. Without an identifier stamped onto both the log and the trace, correlating them means guessing by timestamp and hoping nothing else touched that host in the same second.

The general mechanism: a log integration reads the active span

Every tracer keeps the currently active span in some form of request-scoped context — thread-local in a threaded runtime, async-local (or continuation-local) in an event-loop runtime. A log injection integration is a small hook into your logging library — a formatter, a processor, or a patched logger method — that runs on every log record and asks the tracer “what span is active right now?” If there is one, it copies that span’s trace_id and span_id onto the record before it is emitted. Enable it once, and every log statement already in the codebase benefits, without being touched individually.

One concrete example: Node.js

src/log-injection-init.js

require('dd-trace').init({
  logInjection: true
});

That option is the entire integration step for a Node.js service using dd-trace. Once it is set, any log emitted through a supported logging library (pino, winston, bunyan) automatically gets the active trace context attached to its structured output — no change to any individual logger.info(...) or logger.error(...) call anywhere in the app.

🐶 Proof: the key is logInjection, camelCase — not log_injection

dd-trace’s own typings (node_modules/dd-trace/index.d.ts) declare the option as logInjection?: boolean with @env DD_LOGS_INJECTION. The installed package’s supported-configurations.json (the same file npm run verify’s --options mode reads to check every fence in this course) lists exactly one accepted configurationNames entry for DD_LOGS_INJECTION: "logInjection". There is no log_injection anywhere in either source.

Proof: an unknown option key is a silent no-op, not an error

This matters because a plain JavaScript object literal never rejects a key it doesn’t recognize — dd-trace just never looks at it. Installed [email protected] in a scratch directory (matching this course’s pinned version) and dumped the tracer’s real resolved config three ways — t._tracer._config.logInjection is dd-trace’s own internal, already-merged setting, and DD_TRACE_STARTUP_LOGS (default true, per supported-configurations.json) additionally prints the same picture unprompted at init() time as a DATADOG TRACER CONFIGURATION - log line, so you don’t even need to know about the private field to see it:

$ node -e "const t=require('dd-trace').init({logInjection:false,service:'probe'}); console.log(t._tracer._config.logInjection)"
DATADOG TRACER CONFIGURATION - {...,"log_injection_enabled":false,...}
camelCase logInjection:false -> false          # did what was asked

$ node -e "const t=require('dd-trace').init({log_injection:false,service:'probe'}); console.log(t._tracer._config.logInjection)"
DATADOG TRACER CONFIGURATION - {...,"log_injection_enabled":true,...}
snake_case log_injection:false -> true         # silently ignored -- still the untouched default

$ node -e "const t=require('dd-trace').init({service:'probe'}); console.log(t._tracer._config.logInjection)"
no logInjection key at all -> true             # true is the real default either way

Because the real default is already true, log_injection: true in the old version of this example “looked like it worked” by pure coincidence — but anyone who copies the same misspelled pattern to write log_injection: false, intending to turn injection off (a real, common need for a service that must not leak trace_id into a log destination shared outside the org), silently gets no such thing. npm run verify’s --options mode exists specifically to catch this class of hallucinated key before it ships: it checks every top-level key in a collected tracer.init({...}) fence against the real, installed .d.ts — the fence above (logInjection: true) passes; log_injection: true would not have been collected as valid in the first place.

Trace context propagation: how two services agree it’s the same trace

Log injection answers “which trace is this log line part of.” A separate, related question is how the trace itself stays one trace across a network call between two services — and the answer is a small set of HTTP headers a tracer injects on the way out and extracts on the way in. Ran a dd-trace-instrumented http.get() against a local HTTP server that only prints the headers it received — nothing left this machine, and DD_TRACE_AGENT_URL pointed at a closed local port so there was no live agent involved either:

$ DD_TRACE_PROPAGATION_STYLE=datadog,tracecontext node propagation.js
--- headers received by downstream server ---
x-datadog-trace-id: 5586879601662099183
x-datadog-parent-id: 703201510884566073
x-datadog-sampling-priority: 1
x-datadog-tags: _dd.p.tid=6abbb93000000000,_dd.p.dm=-0
traceparent: 00-6abbb930000000004d889565abf1feef-09c2460c65cae439-01
tracestate: dd=t.dm:-0;t.tid:6abbb93000000000;s:1;p:09c2460c65cae439

x-datadog-trace-id and x-datadog-parent-id are Datadog’s own native propagation format; traceparent/tracestate are the W3C Trace Context standard. Both rode on the same outgoing request because DD_TRACE_PROPAGATION_STYLE was set to datadog,tracecontext — a tracer can inject (and accept) more than one format at once, which is exactly what makes it possible to sit between a legacy Datadog-only service and a newer OpenTelemetry-instrumented one.

DD_TRACE_PROPAGATION_STYLE’s real accepted values, read straight from the installed package’s parsers.js (VALID_PROPAGATION_STYLES) — datadog, tracecontext, b3, b3 single header (an alias for b3 from major version 6 onward), b3multi, baggage, none. The Node.js library-config docs (docs.datadoghq.com/tracing/trace_collection/library_config/nodejs/) confirm the default: datadog,tracecontext,baggage. Switching styles changes the wire format completely — same trace, different headers:

$ DD_TRACE_PROPAGATION_STYLE=b3multi node propagation.js
x-b3-traceid: 6abbb93e00000000041b1cd0943a09ac
x-b3-spanid: 2a31fba7df01f8bd
x-b3-sampled: 1
x-b3-parentspanid: 041b1cd0943a09ac

$ DD_TRACE_PROPAGATION_STYLE=b3 node propagation.js
b3: 6abbb93e00000000256681dd9f945d47-24d519d1a7e5f9c8-1-256681dd9f945d47

$ DD_TRACE_PROPAGATION_STYLE=none node propagation.js
--- headers received by downstream server ---
                                                 # (nothing -- no propagation headers injected at all)

That last run is the practical trap: if two services in a request path have DD_TRACE_PROPAGATION_STYLE sets with zero format in common (one only injects b3multi, the other only extracts datadog), the trace silently splits into two disconnected traces at that hop — no error anywhere, just a service map with a gap in it. This is the network-level twin of the logInjection bug above: a mismatch that produces no exception, only missing data.

The dd.* convention: identity riding along in the log line

{
  "level": "error",
  "message": "Failed to charge card for order 48213",
  "dd": {
    "trace_id": "6746734253672554013",
    "span_id": "3993638273767594310",
    "env": "production",
    "service": "checkout-service",
    "version": "2.4.1"
  }
}

Datadog tracers converge on a dd.* namespace for these injected fields. dd.trace_id and dd.span_id are the pivot keys — they name the exact trace and the exact span that was executing when this line was written. dd.env, dd.service, and dd.version are the unified service tagging triple riding along too, which means this single log line carries enough identity to also be found through the structured logging and facets built out in the Log Management module — it is not just correlatable to a trace, it is a first-class faceted log event in its own right. Ran the equivalent Node.js code for real — winston configured with logInjection: true and a JSON formatter, one logger.error() call inside an active span — and it produces exactly this shape without any manual field-setting:

$ node logcorrelate.js
{"dd":{"env":"production","service":"checkout-service","span_id":"5160495945473134754",
"trace_id":"6abbb93800000000479dc3b88ec510a2","version":"2.4.1"},"level":"error",
"message":"Failed to charge card for order 48213"}

The Python equivalent: DD_LOGS_INJECTION and ddtrace-run

ddtrace (Python) uses an environment variable rather than a programmatic key for this: DD_LOGS_INJECTION. Installed the pinned ddtrace==4.15.2 in a scratch venv and introspected the real, live config object instead of guessing from memory — worth noting the attribute name changed between major versions of the package itself, which is exactly the kind of thing that goes stale in an AI model’s training data:

$ python -c "from ddtrace import config; print(config._logs_injection)"
True                                              # real default, this pinned version

$ DD_LOGS_INJECTION=false python -c "from ddtrace import config; print(config._logs_injection)"
False

$ DD_LOGS_INJECTION=true python -c "from ddtrace import config; print(config._logs_injection)"
True

Setting the config attribute in code after import is not the documented activation path — the real mechanism patches the standard logging module’s record formatting, and that patch is applied through ddtrace-run (or ddtrace.patch_all()), not by touching config directly. Ran a plain logging-based script with a format string referencing %(dd.trace_id)s/%(dd.span_id)s/%(dd.service)s/%(dd.env)s/%(dd.version)s under ddtrace-run with DD_LOGS_INJECTION=true:

$ DD_LOGS_INJECTION=true DD_SERVICE=checkout-service DD_ENV=production DD_VERSION=2.4.1 \
  ddtrace-run python logcorrelate.py
2026-09-29 20:18:51,330 ERROR [__main__] [dd.service=checkout-service dd.env=production
dd.version=2.4.1 dd.trace_id=6abbbabb000000005b560a95a242be0f
dd.span_id=8465665182175932103] - Failed to charge card for order 48213

Same idea as Node’s logInjection: true, same dd.* field names, different activation mechanism: an env var plus the ddtrace-run wrapper (or ddtrace.patch_all() in-process), rather than a key inside tracer.init(). ddtrace-run --help confirms the binary is real and documented, not a hallucinated entry point.

The payoff: one click, not a manual search

Before log injection, an error-severity log line sits by itself, with no easy way to see the request around it — what called this service, what it called next, where the time went. After log injection, because the log carries dd.trace_id, Datadog can put a “view trace” pivot directly on that log line in the Logs Explorer — one click, and you land on the exact distributed trace, with every span across every service that took part in that request, spans that never looked at the log at all.

flowchart LR
  A[Incoming request] --> B[Tracer starts span]
  B --> C["App code calls logger.error(...)"]
  C --> D["Log injection hook reads active span"]
  D --> E["Log emitted with dd.trace_id, dd.span_id, dd.env/service/version"]
  E --> F[Datadog Log Management]
  F -->|click dd.trace_id| G[APM distributed trace view]

From a log line to its trace

🐶 The one-line takeaway

Log injection is the tracer handing its active trace_id/span_id to your logging library — enable it once (logInjection: true in dd-trace, or DD_LOGS_INJECTION=true with ddtrace-run in Python), and the dd.* fields it stamps onto every log line turn “here’s an error, good luck” into a one-click pivot to the exact distributed trace that produced it. That same trace stays one trace across a network hop only because both sides agree on a DD_TRACE_PROPAGATION_STYLE.

Reading AI-generated code

🐛 Spot the bug

// AI comment: "Enable log-trace correlation for our checkout service"
require('dd-trace').init({
service: 'checkout-service',
env: 'production',
log_injection: true
});

// elsewhere, for a service that must NOT leak trace_id into a
// log destination shared outside the org:
// require('dd-trace').init({ log_injection: false });

Show the answer

This compiles and runs without a single warning — a plain object literal never rejects an unrecognized key. The bug, proven above with a real tracer config dump: log_injection is not a dd-trace option; the real key is logInjection (camelCase, DD_LOGS_INJECTION at the env-var level). Because the real default for log injection is already true, the first snippet “works” purely by accident — but the second snippet, which exists specifically to turn injection off for a compliance reason, does nothing at all: the service keeps injecting trace_id/span_id into every log line, silently, exactly the outcome the AI-generated comment says it was trying to prevent. The fix is logInjection: true / logInjection: false — and npm run verify’s --options mode in this course’s own harness would have caught this by checking the key against the pinned package’s real .d.ts before it ever shipped.

Mental Model

Think of log injection and trace propagation as the same idea applied at two different scopes. Log injection is a tracer handing its currently active span’s identifiers sideways, to a logging library running in the very same process. Propagation headers are a tracer handing that same trace’s identifiers forward, over the network, to the next process. Both are “stamp the active trace context onto something that isn’t the trace itself” — one stamps a log record, the other stamps an HTTP request — and both fail exactly the same way when misconfigured: not with an exception, but with a gap. A log with no dd.trace_id just looks like an ordinary log. A request with no (or mismatched) propagation headers just starts a brand-new trace instead of continuing the old one. Neither failure throws; both only show up as “the pivot I expected isn’t there.”

Trade-offs

• logInjection: true (or DD_LOGS_INJECTION=true) vs. leaving it off — turning it on is one flag and costs nothing at the network level (no data leaves the process any differently), but it does mean trace_id/span_id values now ride inside every log line, which matters if those logs are ever shipped somewhere outside your own Datadog org’s control.
• Multiple DD_TRACE_PROPAGATION_STYLE formats at once vs. just one — injecting datadog,tracecontext together (proven above) makes a service interoperate with both legacy Datadog-only and W3C-standard tracers, at the cost of slightly larger request headers and one more thing to keep consistent across every service in the request path.
• Debugging via a real config dump (DD_TRACE_STARTUP_LOGS, _config introspection) vs. trusting the code you wrote — reading the tracer’s own resolved config is slower than assuming your init() call did what you meant, but it is the only way that actually catches a silently-ignored key like log_injection before it reaches production.

Common Misconceptions

• “A misspelled tracer.init() option throws or warns.” No — proven above: log_injection: true/log_injection: false both run cleanly with no error, no warning, nothing in stderr. JavaScript object literals never validate their keys against anything.
• “log_injection: true in this lesson’s old example was correct because it worked.” No — proven above: it “worked” only because true is already the untouched default. The exact same typo with log_injection: false, intending to turn injection off, is silently ineffective.
• “Trace propagation headers are one fixed format.” No — proven above: DD_TRACE_PROPAGATION_STYLE can select Datadog-native headers, W3C traceparent/tracestate, B3 (single or multi-header), or none, and a tracer can inject several formats on the same request simultaneously.
• “If propagation is misconfigured, you’ll see an error.” No — proven above: setting DD_TRACE_PROPAGATION_STYLE=none produces a completely clean run with zero propagation headers sent; the downstream service just starts a new, disconnected trace. Nothing throws.

What does a tracer's log injection integration actually do to a log record?

It deletes low-severity log lines before they are emitted It reads the currently active span and attaches its trace_id and span_id to the log record It replaces the log message with the trace itself It sends the log directly to the APM backend instead of Log Management

In require('dd-trace').init({ logInjection: true }), what is required elsewhere in the app to get injected trace context on every log line?

Nothing else — no changes to individual logger.info/logger.error calls are required Every log statement must be rewritten to manually pass trace_id A separate Grok parser must be written for each log line The logging library must be replaced with dd-trace's own logger

A tracer.init() call is given { log_injection: true } instead of { logInjection: true }. What actually happens when the app runs?

dd-trace throws a TypeError at init() because the key is unrecognized dd-trace prints a deprecation warning but still enables log injection The unknown key is silently ignored -- log injection stays at whatever its real default already was dd-trace automatically corrects the key name to logInjection

What do dd.env, dd.service, and dd.version represent when they show up in an injected log line?

A random trace sampling decision The unified service tagging triple, the same identity used across metrics and traces The Datadog site the log was sent to The log's retention period

Two services in the same request path have DD_TRACE_PROPAGATION_STYLE set to formats that share nothing in common (e.g. one only injects b3multi, the other only extracts datadog). What happens to the trace?

dd-trace throws a propagation error and the request fails The trace silently splits into two disconnected traces at that network hop -- no exception, just a gap in the service map Both services automatically fall back to the W3C traceparent header The request is blocked until the styles are reconciled

What is the concrete payoff of connecting a log line to its trace via dd.trace_id?

Logs are indexed faster You can delete the trace and keep only the log From that one log line you can pivot directly to the full distributed trace that produced it The log line no longer needs a service tag

Submit

Mark as complete