diagnostics_channel: specialized tracing channels

[Qard]

This is still a work-in-progress, but I want to share this before the collab summit so people can see the direction I'm trying to go with this and think about it for the upcoming session on these and other Observability changes I'm working on.

The general idea is that TracingChannel having sync, callback, and promise trace functions was a bit inflexible. What I'm going for here is to split apart concerns into three tracing categories: calls, parameter mapping for callbacks, and return value mapping for promises and iterators.

I'll continue working on this, and especially improving the docs to explain these concepts in more detail.

cc @nodejs/diagnostics

[codecov]

Codecov Report

❌ Patch coverage is 95.97990% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.80%. Comparing base (bf1aebc) to head (1597d07).
⚠️ Report is 29 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/diagnostics_channel.js	95.97%	24 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62641      +/-   ##
==========================================
+ Coverage   89.72%   89.80%   +0.08%     
==========================================
  Files         695      697       +2     
  Lines      214464   216293    +1829     
  Branches    41067    41405     +338     
==========================================
+ Hits       192420   194251    +1831     
- Misses      14106    14135      +29     
+ Partials     7938     7907      -31     

Files with missing lines	Coverage Δ
lib/diagnostics_channel.js	96.90% <95.97%> (-1.23%)	⬇️

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

[jsumners-nr]

I'm having a bit of difficulty following these changes. I think having an example of usage for each of the methods will be very helpful.

[Qard]

Yes, I'll get to documenting it better. The general idea is to split calls from continuations, and to split different forms of continuation from each other.

const syncChannel = dc.syncTracingChannel('test')
const callbackChannel = dc.callbackTracingChannel('test')
const promiseChannel = dc.promiseTracingChannel('test')

function callbackOrPromiseFn(cb) {
  if (cb) return setImmediate(cb)
  return new Promise(resolve => setImmediate(resolve))
}

// Wrap the sync portion of any call
const wrappedFoo = syncChannel.wrap(callbackOrPromiseFn, {
  // Wrap the callback to produce asyncStart/asyncEnd, if present
  wrapArgs(args) {
    if (!args.length) return []
    return [ callbackChannel.wrap(args[0]) ]
  },
  // Wrap the returned promise to produce asyncStart/asyncEnd, if present
  mapOutcome(maybePromise) {
    if (!Promise.isPromise(maybePromise)) return maybePromise
    return promiseChannel.wrap(maybePromise)
  }
})

It's a bit more verbose than what we have now, but a lot more flexible to compose different patterns user code may do. We can also build the higher-level abstractions over top of this for the cases where simpler abstractions are viable.

[jsumners-nr]

Thank you. That example is very helpful.