feat(otel-thread-ctx): Node.js OTEP-4947 thread-context writer (#9210)

Mirrors the active trace ID, span ID, local root span ID and current endpoint
into a thread-local OTEP-4947 record, so an out-of-process eBPF reader can
attribute samples without going through the tracer. The record is discovered via
the otel_thread_ctx_nodejs_v1 TLS symbol exported by the @datadog/pprof addon,
and decoded using an OTEP-4719 process context published through libdatadog's
process discovery (threadlocal.* attribute key map, schema version, and the V8
layout constants a reader needs to walk into the record).

Off by default, behind DD_TRACE_OTEL_CTX_ENABLED. Requires Linux and an active
AsyncContextFrame (default from Node 24, opt-in on 22/23), and refuses to start
unless the installed @datadog/pprof exposes every API member the writer calls
and a context can actually be installed in this process — an unusable pprof
costs a log line rather than an exception thrown from a hot-path diagnostic
channel subscriber.

One ThreadContext is built per span on first activation and cached on the span,
so re-entry in another async-context frame re-installs the same reference rather
than allocating. On span finish the record is invalidated in place, which drops
it out of scope for every frame that inherited it — sibling frames and
continuations the span scheduled before finishing — since no later storage event
reaches those.

The endpoint is held back until its value settles: plugins publish interim
routing tags, and datadog-plugin-next seeds resource.name with the bare request
method, so publishing early would leave a reader attributing samples to "GET".
Once a request's endpoint resolves it is appended to every record built under
that request, the request span's own and each descendant's.

Author: szegedi

.github/CODEOWNERS

@@ -369,8 +369,13 @@
 /integration-tests/profiler/ @DataDog/profiling-js
 
 /packages/dd-trace/*/profiling/ @DataDog/profiling-js
+/packages/dd-trace/src/otel-thread-ctx.js @DataDog/profiling-js
 /packages/dd-trace/src/profiler.js @DataDog/profiling-js
+/packages/dd-trace/src/storage-channels.js @DataDog/profiling-js @DataDog/apm-sdk-capabilities-js
+/packages/dd-trace/src/web-tags-cache.js @DataDog/profiling-js
 /packages/dd-trace/test/exporters/common/form-data.spec.js @DataDog/profiling-js
+/packages/dd-trace/test/otel-thread-ctx.spec.js @DataDog/profiling-js
+/packages/dd-trace/test/web-tags-cache.spec.js @DataDog/profiling-js
 
 # Language Platform
 /* @DataDog/lang-platform-js

.github/workflows/profiling.yml

@@ -32,6 +32,7 @@ jobs:
       - uses: ./.github/actions/install
       - run: npm run test:profiler:ci
       - run: npm run test:integration:profiler:coverage
+      - run: npm run test:otel-thread-ctx
       - uses: ./.github/actions/coverage
         with:
           flags: profiling-macos
@@ -60,6 +61,7 @@ jobs:
       - uses: ./.github/actions/node/latest
       - run: npm run test:profiler:ci
       - run: npm run test:integration:profiler:coverage
+      - run: npm run test:otel-thread-ctx
       - uses: ./.github/actions/coverage
         with:
           flags: profiling-ubuntu
@@ -118,6 +120,7 @@ jobs:
           ) | ForEach-Object { "$_=" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8 }
       - run: npm run test:profiler:ci
       - run: npm run test:integration:profiler:coverage
+      - run: npm run test:otel-thread-ctx
       - uses: ./.github/actions/node-crash-report
         if: failure()
       # Upload any WER minidumps that landed during this job, even on

package.json

@@ -71,6 +71,8 @@
     "test:plugins:upstream": "node ./packages/dd-trace/test/plugins/suite.js",
     "test:profiler": "node scripts/mocha-parallel-files.js --expose-gc --timeout 30000 -- \"packages/dd-trace/test/profiling/**/*.spec.js\"",
     "test:profiler:ci": "node scripts/c8-ci.js test:profiler",
+    "test:otel-thread-ctx": "mocha --timeout 60000 packages/dd-trace/test/otel-thread-ctx.spec.js",
+    "test:docker:otel-thread-ctx": "./scripts/docker/run-otel-thread-ctx-spec.sh",
     "test:integration": "mocha --timeout 60000 \"integration-tests/*.spec.js\"",
     "test:integration:coverage": "node ./integration-tests/coverage/run-suite.js --timeout 60000 \"integration-tests/*.spec.js\"",
     "test:integration:aiguard": "mocha --timeout 60000 \"integration-tests/aiguard/*.spec.js\"",
@@ -180,7 +182,7 @@
     "opentracing": ">=0.14.7"
   },
   "optionalDependencies": {
-    "@datadog/libdatadog": "0.9.4",
+    "@datadog/libdatadog": "0.12.1",
     "@datadog/native-appsec": "11.0.1",
     "@datadog/native-iast-taint-tracking": "4.2.0",
     "@datadog/native-metrics": "3.1.2",

packages/dd-trace/src/config/generated-config-types.d.ts

@@ -340,6 +340,7 @@ export interface GeneratedConfig {
   DD_TRACE_OPENSEARCH_PROJECT_OPENSEARCH_ENABLED: boolean;
   DD_TRACE_OPENTELEMETRY_SDK_TRACE_NODE_ENABLED: boolean;
   DD_TRACE_ORACLEDB_ENABLED: boolean;
+  DD_TRACE_OTEL_CTX_ENABLED: boolean;
   DD_TRACE_OTEL_ENABLED: boolean;
   DD_TRACE_OTEL_SEMANTICS_ENABLED: boolean;
   DD_TRACE_PASSPORT_ENABLED: boolean;
@@ -1040,6 +1041,7 @@ export interface GeneratedEnvVarConfig {
   DD_TRACE_OPENSEARCH_PROJECT_OPENSEARCH_ENABLED: boolean;
   DD_TRACE_OPENTELEMETRY_SDK_TRACE_NODE_ENABLED: boolean;
   DD_TRACE_ORACLEDB_ENABLED: boolean;
+  DD_TRACE_OTEL_CTX_ENABLED: boolean;
   DD_TRACE_OTEL_ENABLED: boolean;
   DD_TRACE_OTEL_SEMANTICS_ENABLED: boolean;
   DD_TRACE_PARTIAL_FLUSH_MIN_SPANS: number;

packages/dd-trace/src/config/supported-configurations.json

@@ -3518,6 +3518,13 @@
         "default": "false"
       }
     ],
+    "DD_TRACE_OTEL_CTX_ENABLED": [
+      {
+        "implementation": "A",
+        "type": "boolean",
+        "default": "false"
+      }
+    ],
     "DD_TRACE_PARTIAL_FLUSH_MIN_SPANS": [
       {
         "implementation": "B",