Publish OTEP-4947 process-context metadata via process discovery

Sets up the OTEP-4719 process context so an out-of-process reader can decode
the on-the-wire records the thread-context writer emits. The metadata is
published through libdatadog-nodejs's process-discovery napi crate: bumped
here to 0.12.0, which exposes the ThreadLocalMetadata substruct with the full
'threadlocal.*' block (attribute key map, schema-version string, and extra
KeyValues for reader-side layout constants).

The pieces:

- Add getThreadLocalMetadata() in otel-thread-ctx.js. Pulls the process-context
  snapshot from @datadog/pprof (its otelThreadCtx.getProcessContextAttributes
  is the source of truth for the schema-version string and V8 layout constants
  the reader needs) and reshapes it into the napi ThreadLocalMetadata form:
  { attributeKeys, schemaVersion, extraAttributes: [{ key, intValue|stringValue }] }.
  Returns undefined when @datadog/pprof isn't installed or doesn't expose the
  helper.

- Wire tracer_metadata.js to pass the substruct (or undefined) as the last
  positional arg to processDiscovery.TracerMetadata(...), replacing the flat
  threadlocalAttributeKeys array. Gated on the same DD_TRACE_OTEL_CTX_ENABLED
  flag that activates the writer.

- Bump the @DataDog/libdatadog optionalDependency from 0.10.0 to 0.12.0.

Author: szegedi

packages/dd-trace/src/otel-thread-ctx.js

@@ -69,12 +69,26 @@ const pendingEndpoints = new WeakMap()
 // convention (mirrors libdatadog's libdd-otel-thread-ctx, where
 // `local_root_span_id` is always the first entry in
 // `threadlocal.attribute_key_map`), encoded as a 16-character lowercase
-// hex string. Endpoint, thread name, and thread id follow.
+// hex string. Endpoint, thread name, and thread id follow. Adding more
+// means assigning the next index and updating ATTRIBUTE_KEYS
+// accordingly.
 const LOCAL_ROOT_SPAN_ID_IDX = 0
 const ENDPOINT_IDX = 1
 const THREAD_NAME_IDX = 2
 const THREAD_ID_IDX = 3
 
+// The dd-trace-js-supplied subset of the OTEP-4719 attribute_key_map
+// (the implicit `datadog.local_root_span_id` at wire index 0 is
+// prepended by libdatadog when it publishes the process context, so it
+// is NOT listed here). Index N here corresponds to wire key index N+1.
+// Kept in sync with the positional indices above.
+// Also see https://docs.google.com/document/d/1IwjjVJzEChcFPcnVV2N5Kkjg-4_Q4v4Q3ojpxntbdvY/edit?pli=1&tab=t.efaosgjya44c#bookmark=id.700gvw31vb7h
+const ATTRIBUTE_KEYS = [
+  'datadog.trace_endpoint',
+  'datadog.thread_name',
+  'datadog.thread_id',
+]
+
 // Stable per-thread values baked into every record. Same shape as the
 // profiler's `eventLoopThreadName` in profiling/profilers/shared.js.
 const THREAD_NAME = (isMainThread ? 'Main' : `Worker #${threadId}`) + ' Event Loop'
@@ -224,6 +238,51 @@ function onWebTagsResolved (span) {
   }
 }
 
+// Every otelThreadCtx member the writer calls, checked before it starts. Anything
+// missing would otherwise surface from inside a diagnostic-channel subscriber on
+// a hot path, where an exception lands in application code: a ThreadContext
+// without invalidate() would throw out of onSpanFinished and up through
+// DatadogSpan#finish() the first time an activated span finished.
+//
+// Returns the name of the first missing member, or undefined when the surface is
+// complete.
+function missingApiMember (ns) {
+  if (!ns) return 'otelThreadCtx'
+  for (const name of ['ThreadContext', 'getContext', 'clearContext', 'getProcessContextAttributes']) {
+    if (typeof ns[name] !== 'function') return name
+  }
+  for (const name of ['appendAttributes', 'enter', 'invalidate']) {
+    if (typeof ns.ThreadContext.prototype[name] !== 'function') return `ThreadContext.prototype.${name}`
+  }
+}
+
+// Install and detach one throwaway context, to establish that this process can
+// actually do it before any span depends on it.
+//
+// @datadog/pprof decides whether AsyncContextFrame is available by inspecting
+// `process.execArgv`, and throws from enter() when it concludes it isn't. That
+// disagrees with the feature detection behind `isACFActive` whenever the flag
+// reached Node by another route: `NODE_OPTIONS=--experimental-async-context-frame`
+// is accepted on Node 22 and 23 and leaves `execArgv` empty, and a worker thread
+// created with an explicit `execArgv` loses it too. Since our subscribers run
+// inline with `storage.enterWith`, letting that throw would put the exception in
+// application code on the first span activation, so find out here instead, where
+// declining to start is still an option.
+function canInstallContext (ns) {
+  try {
+    // Zero-filled ids: the record is only readable while it is installed, which
+    // is for the length of this function, and an all-zero trace id identifies
+    // nothing.
+    const probe = new ns.ThreadContext(new Uint8Array(16), new Uint8Array(8))
+    probe.enter()
+    ns.clearContext()
+    return true
+  } catch (e) {
+    log.warn('OTEP-4947 thread context writer: @datadog/pprof cannot install a thread context', e)
+    return false
+  }
+}
+
 function start () {
   if (started) return true
   if (process.platform !== 'linux') {
@@ -244,14 +303,15 @@ function start () {
     return false
   }
   const ns = pprofMod.otelThreadCtx
-  if (!ns || typeof ns.ThreadContext !== 'function' ||
-      typeof ns.getContext !== 'function' ||
-      typeof ns.clearContext !== 'function') {
+  const missing = missingApiMember(ns)
+  if (missing !== undefined) {
     log.warn(
-      'OTEP-4947 thread context writer: installed @datadog/pprof does not expose the otelThreadCtx API'
+      'OTEP-4947 thread context writer: installed @datadog/pprof does not expose the otelThreadCtx API (missing %s)',
+      missing
     )
     return false
   }
+  if (!canInstallContext(ns)) return false
   ThreadContext = ns.ThreadContext
   getContext = ns.getContext
   clearContext = ns.clearContext
@@ -275,4 +335,43 @@ function start () {
   return true
 }
 
-module.exports = { start }
+// Snapshot of the OTEP-4719 process-context attributes describing this
+// writer's on-the-wire record schema — schema-version string, the caller-side
+// attribute key map, and the V8 layout constants a reader needs to walk from
+// our discovery TLS symbol into the record. Returned in the shape libdatadog's
+// napi ThreadLocalMetadata expects:
+//
+//   { attributeKeys, schemaVersion, extraAttributes: [{ key, intValue|stringValue }] }
+//
+// Returns undefined unless start() succeeded. Callers should treat that as
+// "no threadlocal block" (equivalent to the flag being off) — otherwise we'd
+// publish process-context metadata advertising a decodable OTEP-4947 stream
+// while no writer is producing records.
+function getThreadLocalMetadata () {
+  if (!started) return
+  // start() verified @datadog/pprof.otelThreadCtx exposes the full API
+  // surface (ThreadContext/getContext/clearContext/getProcessContextAttributes),
+  // so this require is a cached lookup and the method is guaranteed present.
+  const pca = require('@datadog/pprof').otelThreadCtx
+    .getProcessContextAttributes(ATTRIBUTE_KEYS)
+  const extraAttributes = []
+  for (const [key, value] of Object.entries(pca)) {
+    if (key === 'threadlocal.schema_version' || key === 'threadlocal.attribute_key_map') continue
+    if (typeof value === 'number' && Number.isInteger(value)) {
+      extraAttributes.push({ key, intValue: value })
+    } else if (typeof value === 'string') {
+      extraAttributes.push({ key, stringValue: value })
+    } else {
+      throw new TypeError(
+        `OTEP-4947 process-context attribute ${JSON.stringify(key)} has unsupported value type: ${typeof value}`
+      )
+    }
+  }
+  return {
+    attributeKeys: [...pca['threadlocal.attribute_key_map']],
+    schemaVersion: pca['threadlocal.schema_version'],
+    extraAttributes,
+  }
+}
+
+module.exports = { start, ATTRIBUTE_KEYS, getThreadLocalMetadata }

packages/dd-trace/src/tracer_metadata.js

@@ -18,6 +18,18 @@ function storeConfig (config) {
       ? (processTags.serialized || null)
       : null
 
+    // OTEP-4947 thread-context writer metadata, published as part of the
+    // OTel process context so an out-of-process reader can decode the
+    // on-wire record: the attribute key map (libdatadog prepends the
+    // implicit `datadog.local_root_span_id` at wire index 0, so we only
+    // supply our own additional keys), the schema-version string, and
+    // the V8 layout constants the reader needs. Gated on the same config
+    // flag that activates the writer; undefined when off or when
+    // @datadog/pprof isn't installed to provide the values.
+    const threadlocalMetadata = config.DD_TRACE_OTEL_CTX_ENABLED
+      ? require('./otel-thread-ctx').getThreadLocalMetadata()
+      : undefined
+
     const metadata = new processDiscovery.TracerMetadata(
       config.tags['runtime-id'],
       tracerVersion,
@@ -26,7 +38,8 @@ function storeConfig (config) {
       config.env || null,
       config.version || null,
       processTagsSerialized,
-      containerId || null
+      containerId || null,
+      threadlocalMetadata
     )
 
     return processDiscovery.storeMetadata(metadata)

packages/dd-trace/test/otel-thread-ctx.spec.js

@@ -99,12 +99,20 @@ describe('otel-thread-ctx', () => {
         this.traceId = traceId
         this.spanId = spanId
         this.attributes = attributes
-        this.appendAttributes = sinon.stub()
-        this.invalidate = sinon.stub()
-        this.isTruncated = sinon.stub().returns(false)
+        // Spied per instance so tests can assert call history on the context,
+        // while the methods themselves stay on the prototype where start()'s
+        // compatibility check looks for them, as they are on the native class.
+        sinon.spy(this, 'appendAttributes')
+        sinon.spy(this, 'invalidate')
         constructedContexts.push(this)
       }
 
+      appendAttributes () {}
+
+      invalidate () {}
+
+      isTruncated () { return false }
+
       enter () { setActive(this) }
     }
 
@@ -114,6 +122,10 @@ describe('otel-thread-ctx', () => {
         ThreadContext: StubThreadContext,
         getContext: sinon.stub().callsFake(() => activeContext),
         clearContext: sinon.stub().callsFake(() => setActive()),
+        getProcessContextAttributes: sinon.stub().returns({
+          'threadlocal.schema_version': 'nodejs_v1_dev',
+          'threadlocal.attribute_key_map': [],
+        }),
       },
     }
 
@@ -186,6 +198,78 @@ describe('otel-thread-ctx', () => {
       assert.equal(m.start(), false)
       sinon.assert.calledWithMatch(log.warn, /otelThreadCtx API/)
     })
+
+    it('returns false when ThreadContext is missing a method the writer calls', () => {
+      // An older or overridden @datadog/pprof can expose the gated namespace
+      // without every ThreadContext method. Starting anyway would defer the
+      // failure to a diagnostic-channel subscriber: a missing invalidate() would
+      // throw out of the span-finish path and up through DatadogSpan#finish()
+      // into application code.
+      for (const method of ['appendAttributes', 'enter', 'invalidate']) {
+        const Incomplete = class extends StubThreadContext {}
+        Incomplete.prototype[method] = undefined
+        const m = loadModule({
+          pprof: {
+            '@noCallThru': true,
+            otelThreadCtx: { ...pprofStub.otelThreadCtx, ThreadContext: Incomplete },
+          },
+        })
+        assert.equal(m.start(), false, `expected start() to refuse a ThreadContext without ${method}`)
+        sinon.assert.calledWithMatch(log.warn, /otelThreadCtx API/, `ThreadContext.prototype.${method}`)
+        log.warn.resetHistory()
+      }
+    })
+
+    it('returns false when a context cannot be installed in this process', () => {
+      // @datadog/pprof infers AsyncContextFrame availability from process.execArgv
+      // and throws from enter() when it concludes it is unavailable, which
+      // disagrees with our own feature detection when the flag arrived via
+      // NODE_OPTIONS or a worker's execArgv was overridden. Subscribers run inline
+      // with storage.enterWith, so this must not be discovered on first activation.
+      const Throwing = class extends StubThreadContext {
+        enter () { throw new Error('async_context_frame support is unavailable') }
+      }
+      const m = loadModule({
+        pprof: {
+          '@noCallThru': true,
+          otelThreadCtx: { ...pprofStub.otelThreadCtx, ThreadContext: Throwing },
+        },
+      })
+      assert.equal(m.start(), false)
+      sinon.assert.calledWithMatch(log.warn, /cannot install a thread context/)
+      // No subscriber may be left behind, so a subsequent activation must not
+      // reach the writer — and so must not hit the throwing enter() either.
+      activeSpan = makeSpan()
+      enterCh.publish()
+      assert.equal(constructedContexts.length, 1) // just the failed probe
+    })
+
+    it('leaves no context installed after the start-up probe succeeds', () => {
+      const m = loadModule()
+      assert.equal(m.start(), true)
+      assert.equal(constructedContexts.length, 1)
+      sinon.assert.calledOnce(pprofStub.otelThreadCtx.clearContext)
+      assert.equal(activeContext, undefined)
+    })
+
+    it('returns false when otelThreadCtx is missing getProcessContextAttributes', () => {
+      // start() must refuse to install subscribers if the metadata publisher
+      // can't be produced — otherwise the writer emits records that no reader
+      // can decode.
+      const m = loadModule({
+        pprof: {
+          '@noCallThru': true,
+          otelThreadCtx: {
+            ThreadContext: StubThreadContext,
+            getContext: sinon.stub(),
+            clearContext: sinon.stub(),
+            // no getProcessContextAttributes
+          },
+        },
+      })
+      assert.equal(m.start(), false)
+      sinon.assert.calledWithMatch(log.warn, /otelThreadCtx API/)
+    })
   })
 
   describe('subscribed behavior', () => {
@@ -194,6 +278,11 @@ describe('otel-thread-ctx', () => {
     beforeEach(() => {
       otelThreadCtx = loadModule()
       assert.equal(otelThreadCtx.start(), true)
+      // start() installs and detaches one throwaway context to prove the process
+      // can; drop its traces so the tests below see only their own activity.
+      constructedContexts.length = 0
+      setActive.resetHistory()
+      pprofStub.otelThreadCtx.clearContext.resetHistory()
     })
 
     it('clearContext when no active span', () => {
@@ -513,4 +602,66 @@ describe('otel-thread-ctx', () => {
       assert.equal(constructedContexts.length, 0)
     })
   })
+
+  describe('getThreadLocalMetadata()', () => {
+    // start() is always called before getThreadLocalMetadata() in the
+    // real init sequence (proxy.js kicks off the writer, then storeConfig()
+    // pulls the metadata). getThreadLocalMetadata is a no-op unless start
+    // succeeded, so every happy-path test runs start() first.
+    it('returns undefined when start() has not been called', () => {
+      pprofStub.otelThreadCtx.getProcessContextAttributes = sinon.stub()
+      const m = loadModule()
+      assert.equal(m.getThreadLocalMetadata(), undefined)
+      sinon.assert.notCalled(pprofStub.otelThreadCtx.getProcessContextAttributes)
+    })
+
+    it('returns the process-context snapshot in libdatadog-nodejs shape', () => {
+      pprofStub.otelThreadCtx.getProcessContextAttributes = sinon.stub().returns({
+        'threadlocal.schema_version': 'nodejs_v1_dev',
+        'threadlocal.attribute_key_map': ['datadog.trace_endpoint', 'datadog.thread_name'],
+        'threadlocal.wrapped_object_offset': 24,
+        'threadlocal.tagged_size': 8,
+      })
+      const m = loadModule()
+      assert.equal(m.start(), true)
+      const md = m.getThreadLocalMetadata()
+      sinon.assert.calledOnceWithExactly(
+        pprofStub.otelThreadCtx.getProcessContextAttributes,
+        m.ATTRIBUTE_KEYS
+      )
+      assert.deepEqual(md.attributeKeys, ['datadog.trace_endpoint', 'datadog.thread_name'])
+      assert.equal(md.schemaVersion, 'nodejs_v1_dev')
+      // Order isn't guaranteed since Object.entries is object-key ordered.
+      const byKey = Object.fromEntries(md.extraAttributes.map(a => [a.key, a]))
+      assert.deepEqual(byKey['threadlocal.wrapped_object_offset'],
+        { key: 'threadlocal.wrapped_object_offset', intValue: 24 })
+      assert.deepEqual(byKey['threadlocal.tagged_size'],
+        { key: 'threadlocal.tagged_size', intValue: 8 })
+    })
+
+    it('encodes string-valued extra attributes as stringValue', () => {
+      pprofStub.otelThreadCtx.getProcessContextAttributes = sinon.stub().returns({
+        'threadlocal.schema_version': 'nodejs_v1_dev',
+        'threadlocal.attribute_key_map': [],
+        'threadlocal.runtime.name': 'nodejs',
+      })
+      const m = loadModule()
+      assert.equal(m.start(), true)
+      const md = m.getThreadLocalMetadata()
+      assert.deepEqual(md.extraAttributes, [
+        { key: 'threadlocal.runtime.name', stringValue: 'nodejs' },
+      ])
+    })
+
+    it('throws on an extra attribute with an unsupported value type', () => {
+      pprofStub.otelThreadCtx.getProcessContextAttributes = sinon.stub().returns({
+        'threadlocal.schema_version': 'nodejs_v1_dev',
+        'threadlocal.attribute_key_map': [],
+        'threadlocal.weird': true, // booleans aren't wired through yet
+      })
+      const m = loadModule()
+      assert.equal(m.start(), true)
+      assert.throws(() => m.getThreadLocalMetadata(), /unsupported value type/)
+    })
+  })
 })