diagnostics_channel: add opt-in subscriber suppression via bypassBy and bypassed()

[DivyanshuX9]

Summary

Adds opt-in subscriber suppression to diagnostics_channel so APM
agents can prevent recursive instrumentation when their own internal
code calls into instrumented libraries.

What Changed

lib/diagnostics_channel.js

• Added suppressed(key, fn, thisArg, ...args) - runs fn with
  the given key active in the current async context
• subscribe() and bindStore() accept { subscriberId } option
• Separate lazy storage for bypassed subscribers/stores - normal
  path has zero overhead, ALS is only hit when bypass subscribers exist
• Lazy AsyncLocalStorage initialization via getSuppressionsStorage()
  • required because diagnostics_channel loads during bootstrap before
    async_hooks is available
• Unified validateBypassKey() helper for all key validation

test/parallel/test-diagnostics-channel-suppression.js

• 10 test scenarios covering sync, async, Promise, timer,
  store, nested, and type validation cases

Why

APM agents currently implement suppression themselves using a
custom ALS noop marker - every vendor reimplements the same
pattern differently. Moving it into core:

• Eliminates per-handler overhead on the hot path
• Gives vendors a standard API
• Correctly propagates across Promise/timer boundaries via ALS

Backward Compatibility

• Fully opt-in : existing code unaffected
• Normal subscribers pay zero extra cost
• ALS only initialized and queried when bypass subscribers exist

Naming

As per @bengl final name is "Bypass"

Addresses:#63623

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[DivyanshuX9]

@BridgeAR @bengl @Qard , I am opening this as a implementation
of #63623. Test file is included. Happy to adjust the API shape
or implementation based on your feedback before CI runs.

[codecov]

Codecov Report

❌ Patch coverage is 97.43590% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.13%. Comparing base (58795e9) to head (a86df32).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/diagnostics_channel.js	97.43%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63651      +/-   ##
==========================================
- Coverage   90.16%   90.13%   -0.03%     
==========================================
  Files         744      744              
  Lines      242518   242667     +149     
  Branches    45692    45723      +31     
==========================================
+ Hits       218663   218729      +66     
- Misses      15349    15443      +94     
+ Partials     8506     8495      -11     

Files with missing lines	Coverage Δ
lib/diagnostics_channel.js	97.28% <97.43%> (+<0.01%)	⬆️

... and 33 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.

[Qard]

Tests are missing a lot of necessary common.mustCall(fn) wrappers.

Also, it seems like this was just vibe-coded without reviewing the output before submitting the PR. Please ensure it is in a good state and that the test suite and lint passes before submitting.

[DivyanshuX9]

@Qard , thanks for the detailed review. So far the checklist of what i have fixed in the latest push:

[] Removed the impossible ALS try/catch fallback
[] Removed node_errors.cc changes as you suggested
[] Replaced all IIFE wrappers with plain blocks in tests
[] Added common.mustCall() / common.mustNotCall() to all handlers
[] Ran lint and tests locally , both passing

Ready for re-review and any changes if you want, when you have time please review it.

[Qard]

The node_errors.cc change still seems to be present.

[DivyanshuX9]

@BridgeAR @bengl @rochdev
I opened the docs PR: #64250

Covers bypass(), bypassId on subscribe/bindStore/tracingChannel,the APM recursion use case, and multi-vendor coordination.
Both MJS and CJS examples throughout.

Tell if i'm missing somethin' or I need to add anything else

[Flarna]

Docs are missing

[DivyanshuX9]

@Flarna docs are in PR: #64250
since it is going to be a continuation of this PR , after all the changes and reviews i'll update them.

[Flarna]

I think implementation + tests + docs of a new public API should come in one PR.

[DivyanshuX9]

@Flarna Well once BridgeAR also mentioned about doc

We definitely also need documentation for the feature.

at that time was not sure how far reviews will go ,also @rochdev wanted some examples rightaway, So made a seperate PR for that to keep this one clean , yes if i get a green signal to land this one will will update and merge that pr doc in this one.

[DivyanshuX9]

@Flarna i have moved all the docs here

[DivyanshuX9]

@Flarna , lowkey I have addressed all feedback in latest push:

1. Added Stability: 1.1 - Active development to bypass()
2. Removed bypass example from Overview (not a typical usage pattern)
3. Rewrote key parameter description to clarify no single match required
4. Rewrote description paragraph to focus on behavior, not internals
5. Fixed channel name to http.client.request.start throughout
6. Replaced repeated subscribe/bindStore bypass examples with link to bypass() docs
7. Removed all the unrelated REPLACEME changes entry from tracingChannel.subscribe

Thank you for the thorough review.

[DivyanshuX9]

Stability: 1.1 - Active development

also @Flarna at 251 line is this correct or should i just remove REPLACE ME with the stability:1.1 right away

[Flarna]

No, the REPLACEME is changed by the release tooling when a release is made, see https://github.com/nodejs/node/blob/main/doc/contributing/api-documentation.md#writing-documentation

The stability index is just documentation and independent of that.

[DivyanshuX9]

@BridgeAR following up on your performance concern, ran a microbenchmark on the normal-subscriber hot path (1,000,000 iterations, no bypass() active):

	main	branch	delta
normal-only (no bypass sub)	5.77ms	7.97ms	+2.2ms (+38%)
normal + bypass sub (bypass idle)	14.9ms	19.6ms	+4.7ms (+32%)

Test 1 is the pure normal path with no bypass subscriber registered at all, the overhead is just the _bypassSubscribers !== null null-check plus the extra fields on the channel object, comes out to around 2.2ns per call.
Test 2 is when an APM tool has opted in but bypass() isn't currently active, getBypassStorage().getStore() runs on every publish anyway, that's where the bigger cost comes from (~4.7ns/call over baseline).
Before I touch anything wanted to ask, is the 2.2ns on the pure normal path within acceptable range for this feature, or do you want me to look at avoiding the hidden-class shape change? For test 2 I could try caching the getStore() result per microtask turn but that adds complexity, not sure if its worth it.
Happy to dig into either if you think it matters.