diagnostics_channel: add USDT probes by bengl · Pull Request #62118 · nodejs/node

bengl · 2026-03-05T17:23:49Z

Adds USDT probes that are fired for every diagnostics_channel publish.

nodejs-github-bot · 2026-03-05T17:24:06Z

Review requested:

@nodejs/gyp

RafaelGSS · 2026-03-05T19:18:04Z

+
+#### Platform support
+
+At `./configure` time, Node.js checks for a working `dtrace` tool and


We have removed dtrace support long time ago. Wouldn't it require us to include a new suite for testing it on that environment?

I'm not sure what our build setup looks like now, but yes, everything that was required for the previous incarnation of probes in Node.js would likely be required again with this PR.

I don't think we tested the dtrace stuff previously. I think when it was removed it had be broken for a while (or maybe that was one of the other non-tested removed features).

There's a possible path forward here where headers are pre-generated and added to git (much like we do for other cases of generated headers, in dependencies for example), and then a userland, self-contained test (at least on linux) checks for the placement and activation of the probe.

Alright, I've made some changes (many months later..)

Linux is now default-on with no dtrace build dependency. src/node_provider_linux.h is committed.
It can be regenerated via tools/usdt/generate_headers.py and a --check drift job runs in CI against it.
Default ./configure enables USDT whenever <sys/sdt.h> is present (systemtap-sdt-dev / systemtap-sdt-devel is the only build requirement on Linux).

macOS is opt-in via ./configure --with-dtrace (which at build-time calls dtrace -h -xnolibs).
--without-dtrace still disables everything.

New test-usdt CI job in test-linux.yml:

default: end-to-end bpftrace test as root (verifies the probe fires with the channel name) plus the committed-header drift check

--without-dtrace: pins the no-op tier

Bench (aarch64 VM, benchmark/diagnostics_channel/publish.js, subscribers=1, avg of 2): default ~282M ops/s vs --without-dtrace ~314M ops/s — ~10% on this microbench.

github-actions · 2026-08-03T01:42:30Z

This pull request has been marked as stale due to 90 days of inactivity.
It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.

Implements the approach from the nodejs#62118 review discussion to remove the build-time 'dtrace' dependency on Linux: * Commit the SystemTap-generated probe header (src/node_provider_linux.h, regenerate with tools/usdt/generate_headers.py). USDT support is now on by default on Linux whenever <sys/sdt.h> is available (systemtap-sdt-dev on Debian/Ubuntu, systemtap-sdt-devel on Fedora/RHEL) and never needs a 'dtrace' tool at build time. A committed-header drift check runs in CI. * Make native DTrace opt-in on macOS via the new ./configure --with-dtrace; FreeBSD/illumos remain unsupported pending a 'dtrace -G' link step. --without-dtrace still disables probes everywhere. The always-on <sys/sdt.h> fallback tier is gone. * Add a path-gated test-usdt job to the Linux CI workflow with a default leg that runs the end-to-end bpftrace probe test as root, and a --without-dtrace leg that pins the no-op tier. The generated header is excluded from cpplint like src/node_root_certs.h.

Implements the approach from the nodejs#62118 review discussion to remove the build-time 'dtrace' dependency on Linux: * Commit the SystemTap-generated probe header (src/node_provider_linux.h, regenerate with tools/usdt/generate_headers.py). USDT support is now on by default on Linux whenever <sys/sdt.h> is available (systemtap-sdt-dev on Debian/Ubuntu, systemtap-sdt-devel on Fedora/RHEL) and never needs a 'dtrace' tool at build time. A committed-header drift check runs in CI. * Make native DTrace opt-in on macOS via the new ./configure --with-dtrace; FreeBSD/illumos remain unsupported pending a 'dtrace -G' link step. --without-dtrace still disables probes everywhere. The always-on <sys/sdt.h> fallback tier is gone. * Add a path-gated test-usdt job to the Linux CI workflow with a default leg that runs the end-to-end bpftrace probe test as root, and a --without-dtrace leg that pins the no-op tier. The generated header is excluded from cpplint like src/node_root_certs.h. Signed-off-by: Bryan English <bryan@bryanenglish.com>

jasnell · 2026-09-10T21:15:56Z

+#define NODE_DC_PUBLISH_PROBE(name, msg) NODE_DC_PUBLISH((name), (msg))
+
+// Real semaphore — JS can check it without crossing into C++.
+inline unsigned short* NodeDCPublishSemaphore() {  // NOLINT(runtime/int)


These aren't in any namespace (e.g. namespace node { ... }) ... is that intentional/necessary? If either, that should be documented here.

It's intentional, since we're doing all this wrapping and handling of non-namespaced stuff in here. I'll add a comment to clarify.

jasnell · 2026-09-10T21:23:10Z

+      NodeDCPublishSemaphore(),
+      sizeof(unsigned short),       // NOLINT(runtime/int)
+      [](void*, size_t, void*) {},  // no-op deleter — memory is static
+      nullptr);


This might run into issues when v8 sandbox is enabled. @codebytere

IIUC, arbitrary process memory can't be wrapped/exposed to JS with sandbox enabled. We'll just fall back to non-semaphore mode then (like I'm doing on macOS). Fix incoming.

codecov · 2026-09-10T23:32:26Z

Codecov Report

❌ Patch coverage is 48.48485% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.17%. Comparing base (4bf4c00) to head (6645936).
⚠️ Report is 16 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_diagnostics_channel.cc	0.00%	12 Missing and 5 partials ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #62118   +/-   ##
=======================================
  Coverage   90.17%   90.17%           
=======================================
  Files         771      771           
  Lines      265496   265479   -17     
  Branches    50483    50464   -19     
=======================================
+ Hits       239401   239404    +3     
+ Misses      17052    17018   -34     
- Partials     9043     9057   +14

Files with missing lines	Coverage Δ
lib/diagnostics_channel.js	`97.40% <100.00%> (+0.06%)`	⬆️
src/node_diagnostics_channel.h	`57.14% <ø> (ø)`
src/node_diagnostics_channel.cc	`79.09% <0.00%> (-4.57%)`	⬇️

... and 42 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Fire a `dc__publish` USDT probe for every diagnostics_channel publish, passing the channel name, so tracers such as bpftrace, perf, or SystemTap can observe publish traffic with near-zero cost when nothing is attached. Probes are enabled by default on Linux; --without-dtrace disables them. The probe semaphore is exposed to JS as a Uint16Array over the native semaphore so the publish hot path can gate on one indexed load instead of a binding call. The array is resolved lazily rather than captured at module load: this module is baked into the startup snapshot, and a view captured while building the snapshot is detached when the snapshot is deserialized. Builds without USDT support keep a branch-only path that never calls the binding. Signed-off-by: Bryan English <bryan@bryanenglish.com> Assisted-by: Pi using GLM-5.3

Remove the build-time dtrace dependency on Linux, following the approach discussed in the PR review: generate the SystemTap provider header once with tools/usdt/generate_headers.py and commit it as src/node_provider_linux.h, so Linux builds need only <sys/sdt.h> and never a dtrace tool. --with-dtrace becomes the opt-in switch for macOS; --without-dtrace disables probes entirely. Add a path-filtered test-usdt job to the Linux CI workflow that installs bpftrace and systemtap-sdt-dev, verifies the committed header stays in sync with the generator, builds with and without dtrace, and runs the USDT tests, including a root-only bpftrace end-to-end test that attaches to the dc__publish probe and asserts the channel name argument. Signed-off-by: Bryan English <bryan@bryanenglish.com> Assisted-by: Pi using GLM-5.3

nodejs-github-bot added lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. labels Mar 5, 2026

RafaelGSS reviewed Mar 5, 2026

View reviewed changes

bengl force-pushed the bengl/usdt-dc branch from 5abeea0 to ac101f6 Compare March 5, 2026 20:51

github-actions Bot added the stale Issues and PRs marked stale due to inactivity and scheduled for automatic closure. label Aug 3, 2026

bengl force-pushed the bengl/usdt-dc branch from 4e60afb to d49a2c5 Compare September 9, 2026 14:32

github-actions Bot removed the stale Issues and PRs marked stale due to inactivity and scheduled for automatic closure. label Sep 10, 2026

bengl force-pushed the bengl/usdt-dc branch from d49a2c5 to 22e8015 Compare September 10, 2026 20:55

bengl marked this pull request as ready for review September 10, 2026 20:56

bengl force-pushed the bengl/usdt-dc branch from 22e8015 to 4e1213d Compare September 10, 2026 21:14

jasnell reviewed Sep 10, 2026

View reviewed changes

bengl force-pushed the bengl/usdt-dc branch from 4e1213d to 5a684c8 Compare September 11, 2026 02:22

bengl added 2 commits September 10, 2026 22:51

bengl force-pushed the bengl/usdt-dc branch from 5a684c8 to 6645936 Compare September 11, 2026 13:20

Navigation Menu

Uh oh!

Uh oh!

diagnostics_channel: add USDT probes - #62118

diagnostics_channel: add USDT probes#62118
bengl wants to merge 2 commits into
nodejs:mainfrom
bengl:bengl/usdt-dc

bengl commented Mar 5, 2026

Uh oh!

nodejs-github-bot commented Mar 5, 2026

Uh oh!

RafaelGSS Mar 5, 2026

Uh oh!

bengl Mar 6, 2026

Uh oh!

richardlau Mar 6, 2026

Uh oh!

bengl May 4, 2026

Uh oh!

bengl Sep 9, 2026

Uh oh!

github-actions Bot commented Aug 3, 2026

Uh oh!

jasnell Sep 10, 2026

Uh oh!

bengl Sep 11, 2026

Uh oh!

jasnell Sep 10, 2026

Uh oh!

bengl Sep 11, 2026

Uh oh!

codecov Bot commented Sep 10, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		#### Platform support

		At `./configure` time, Node.js checks for a working `dtrace` tool and

Uh oh!

Uh oh!

Conversation

bengl commented Mar 5, 2026

Uh oh!

nodejs-github-bot commented Mar 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

codecov Bot commented Sep 10, 2026 •

edited

Loading