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.

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. Append-on-realloc updates the wrapper's internal record_ pointer in place, so every async-context frame that holds the same wrapper reference observes the new buffer (no per-CPED record divergence).
• 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). The shape mirrors the wall profiler's setContext/getContext pattern: callers construct one ThreadContext per logical scope (typically per trace span) and re-install the same JS reference on every async-context fire.

• class ThreadContext — constructable from JS via new pprof.otelThreadCtx.ThreadContext(traceId, spanId, attributes?). Instance methods: appendAttributes(attrs) (append-only, mutates the record in place), isTruncated(), and debugBytes() (debug-only). Lifetime is GC-managed: the underlying native record is freed when no JS or async-context-frame reference survives.
• getContext(): ThreadContext | undefined — returns whatever's attached to the active async-context frame.
• setContext(ctx) — installs (or detaches, with undefined) a context in the active async-context frame. Re-installing the same reference across many frames is cheap (no allocation); per-span caching of the context object is the intended usage.
• runWithContext(ctx, fn) — scoped variant: als.run-style.
• makeNamedContext(keys) — returns a NamedContext with buildContext(opts) (resolves namedAttributes against the captured key list and constructs a ThreadContext) plus sugar methods (enterWithContext / runWithContext / clearContext) that compose buildContext with the top-level functions. It also exposes processContextAttributes, a frozen snapshot of the OTEP-4719 entries the caller should publish.

traceId/spanId are raw Uint8Array (16 and 8 bytes; Buffer works as a subclass). 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:

{
    '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

Mocha suite under ts/test/test-otel-thread-ctx.ts covering: ThreadContext construction and input parsing, on-the-wire record encoding (including multibyte UTF-8 truncation at the 255-byte per-value cap), the 612-byte cap and isTruncated, in-place append vs geometric realloc, async propagation, setContext/getContext/runWithContext lifecycle and idempotency, NamedContext.buildContext name resolution, processContextAttributes shape and immutability, 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 158 passing (96 existing pprof tests + the new suite).

[github-actions]

Overall package size

Self size: 2.42 MB
Deduped: 3.12 MB
No deduping: 3.12 MB

Dependency sizes

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

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