Port OTEP-4947 thread-context writer from polarsignals/custom-labels

[szegedi]

Adds a Node.js writer for the OpenTelemetry Thread Local Context Record
(OTEP-4947),
ported from the in-development upstream at
polarsignals/custom-labels#16.
The two codebases will diverge again later; for now this is a snapshot of
the current state.

Draft because the upstream OTEP is still in development and the upstream
custom-labels PR isn't merged either — this PR is here for review and
parallel development, not for landing as-is.

What's in this branch

Native addon (bindings/)

• otel-thread-ctx.cc + otel-thread-ctx.hh: the writer, namespaced as
  dd::OtelThreadCtx::Init(exports) and called from binding.cc.
• The discovery TLS symbol otel_thread_ctx_nodejs_v1 stays in extern \"C\" at
  file scope so it's exported by name through the dd_pprof.node dynsym
  table. It's a 32-byte struct holding the four fields a reader needs:
  cped_slot (V8 isolate's ContinuationPreservedEmbedderData slot
  pointer), als_handle (Global<Object> to the writer's
  AsyncLocalStorage), als_identity_hash (JS identity hash for hash-bucket
  narrowing), and undefined_addr (cached per-isolate undefined singleton
  for clean "no context" detection by the reader).
• Records use a C99 flexible-array-member tail and are right-sized to fit
  the encoded attribute payload, with a 36-byte attrs_data floor (one
  cache line total — matches the OTEP "frugal writer" guidance) and ×2
  geometric growth on append, capped at the OTEP-recommended 612-byte
  attrs_data ceiling.
• binding.gyp adds -mtls-dialect=gnu2 on x86_64 Linux (required by
  OTEP-4947 for TLSDESC; on arm64 TLSDESC is the only dynamic TLS model
  so no flag is needed).

TypeScript layer (ts/src/otel-thread-ctx.ts)

API surface (Linux only; no-op stubs elsewhere):

• runWithContext(fn, opts) — wraps AsyncLocalStorage.run; scopes the
  context to fn.
• enterWithContext(opts) — wraps AsyncLocalStorage.enterWith; attaches
  to the current async scope without a callback boundary.
• clearContext() — detaches any active context (enterWith(undefined)).
  Idempotent.
• appendAttributes(attributes) — appends attributes to the active
  record. Append-only: existing entries are not overwritten. Either
  updates the record in place (when the encoded bytes fit in the current
  allocation's slack) or reallocates with geometric growth.
• isContextTruncated() — sticky boolean; returns true if at any point
  in this context's lifetime an attribute had to be dropped because the
  encoded payload would have exceeded the 612-byte cap.
• makeNamedContext(keys) — returns a NamedContext exposing
  name-addressed variants of all five top-level functions plus
  processContextAttributes, a snapshot of the OTEP-4719 process-context
  entries (schema version, attribute_key_map, plus the V8 layout
  constants — see below) the caller should publish.

opts.traceId/opts.spanId are raw Uint8Array (16 and 8 bytes;
Buffer works as a subclass). opts.attributes is positional: index N
is the value for uint8 key index N on the wire; null/undefined/holes are
skipped. Per-value cap of 255 UTF-8 bytes (uint8 length prefix), total
attrs_data cap of 612 bytes (OTEP-recommended 640-byte total record
minus 28-byte header).

Process-context attributes

makeNamedContext(keys).processContextAttributes exposes a frozen
snapshot ready to spread into whatever OTEP-4719 process-context
publisher the application uses:

```js
{
'threadlocal.schema_version': 'nodejs_v1',
'threadlocal.attribute_key_map': [...keys],
// V8 layout constants captured from the V8 headers the addon was
// compiled against — let the reader walk our wrapper and V8's
// OrderedHashMap layout without doing its own V8-internal-symbol
// lookups for the pointer-compression / sandbox state.
'threadlocal.nodejs_v1.wrapped_object_offset': 24,
'threadlocal.nodejs_v1.tagged_size': 8,
}
```

Tests

65-case mocha suite under ts/test/test-otel-thread-ctx.ts covering:
input parsing and validation, on-the-wire record encoding (including
multibyte UTF-8 truncation at the 255-byte per-value cap), the 612-byte
cap and the isContextTruncated flag, in-place append vs geometric
realloc, async propagation, processContextAttributes shape and
immutability, clearContext semantics, and a readelf --dyn-syms
check that the TLS symbol is exported with the right binding /
visibility / type. The whole describe block is skipped on non-Linux.

A second commit adds a scripts/docker/ Dockerfile + launcher and a
test:docker npm script that builds the addon and runs the full test
suite in a Linux container — useful for running the new tests from
macOS dev machines. End-to-end verified at 161 passing (96
existing pprof tests + the new suite).

[datadog-prod-us1-3]

✨ Fix all issues with BitsAI

⚠️ Warnings

🚦 17 Pipeline jobs failed

Build | asan (20)     

Build | build / darwin-arm64     

Build | build / darwin-x64     

View all 17 failed jobs.

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 64d4d68 | Docs | Datadog PR Page | Give us feedback!}

[github-actions]

Overall package size

Self size: 2.41 MB
Deduped: 2.77 MB
No deduping: 2.77 MB

Dependency sizes

| name | version | self size | total size | |------|---------|-----------|------------| | source-map | 0.7.6 | 185.63 kB | 185.63 kB | | pprof-format | 2.2.1 | 163.06 kB | 163.06 kB | | node-gyp-build | 4.8.4 | 13.86 kB | 13.86 kB |

_{🤖 This report was automatically generated by heaviest-objects-in-the-universe}