feat: add TracingChannel support for native APM instrumentation - #4178

Sorry about the Copilot spam.

I see you're using Claude, my suggestion would be you to report the errors to it, so it can investigate what caused the current code to break before continuing 🙋🏻‍♂️

For example: https://github.com/sidorares/node-mysql2/actions/runs/23071036612/job/67024378058?pr=4178

@logaretm, do you think the Pool Cluster should have its own channel, or could that conflict with the Pool’s existing channel?

Yea, no worries i directed it to the failures.

For the pool cluster, the individual pool connections already get traced via mysql2:pool:connect and mysql2:connect channels, to visulize what that would look like in an APM dashboard or from a user's presective:

  With pool cluster channel:
  mysql2:pool-cluster:connect  [0.2ms]  pattern=SLAVE*, selected=SLAVE2
    └── mysql2:pool:connect    [5ms]    server=slave2-host:3306
        └── mysql2:query       [12ms]   SELECT * FROM users

  Without it (what we already have):
  mysql2:pool:connect          [5ms]    server=slave2-host:3306
    └── mysql2:query           [12ms]   SELECT * FROM users

I don't have a strong opinion on this, OTEL didn't instrument clusters but usually the more channels the merrier as if the APM doesn't subscribe to it then no overhead is introduced. What do you think?

I don't have a strong opinion on this, OTEL didn't instrument clusters but usually the more channels the merrier as if the APM doesn't subscribe to it then no overhead is introduced. What do you think?

I think the current channels are already good. Thanks for the example.

Codecov Report

❌ Patch coverage is 85.16129% with 46 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.32%. Comparing base (cb2df63) to head (9987d30).
⚠️ Report is 4 commits behind head on master.

@@            Coverage Diff             @@
##           master    #4178      +/-   ##
==========================================
- Coverage   90.44%   90.32%   -0.13%     
==========================================
  Files          86       87       +1     
  Lines       13989    14280     +291     
  Branches     1733     1788      +55     
==========================================
+ Hits        12653    12898     +245     
- Misses       1336     1382      +46     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Looks like the skip isn't kicking in, I will check it locally with node 18

Looks like the skip isn't kicking in, I will check it locally with node 18

It seems that the function itself is available, but not all of the necessary implementations are in place. I recommend something like:

if (version <= 18) { // from common.test.js
  skip('TracingChannel requires Node 19.9+ / 20+');
}

I see what's throwing it off, the specific node version in the tests does have tracingChannels but not hasSubscribers.

@wellwelwel should we strictly adhere to zero cost here and require hasSubcribers to be available for tracing to work? or are you okay that older node version won't have that optimization?

should we strictly adhere to zero cost here and require hasSubcribers to be available for tracing to work? or are you okay that older node version won't have that optimization?

Since this would be a limitation of Node.js versions rather than of MySQL2 itself, I would choose to make the option unavailable for versions with "incomplete" support.

This could also be documented as this feature is available starting with Node.js v20, for example.

The overhead will be minimal anyways since if there are no subscribers then nothing really happens. Even propagation context stores would only run if only there are subscribers and then that's okay.

So it's an optimization that exists for newer node versions, but older node won't have it. But happy to stick to all or nothing approach here if you think that's best.

But happy to stick to all or nothing approach here if you think that's best.

I'm fine with the current approach, as long as this is documented. Once all the tests pass, I'll take a closer look at the implementation 🙋🏻‍♂️

For the documentation, I believe this feature should have its own section, similar to how we handle the use of Cloudflare Worker, for example:

@wellwelwel should the docs be in this PR as well, or in a separate PR?

should the docs be in this PR as well, or in a separate PR?

Here, please 🙋🏻‍♂️

• I usually use “Squash and Merge”, so all functionality + commits are grouped. I consider this an interesting way to keep the repository and contributions organized.