I'd like to propose adding first-class TracingChannel support to mysql2, following the pattern established by undici in Node.js core.

TracingChannel is a higher-level API built on top of diagnostics_channel, specifically designed for tracing async operations. It provides structured lifecycle channels (start, end, error, asyncStart, asyncEnd) and handles async context propagation correctly, which was the missing piece that makes existing monkey-patching approaches fragile in real-world async Node.js applications.

Current instrumentations today use IITM (import-in-the-middle) for ESM and RITM (require-in-the-middle) for CJS to monkey-patch Connection.prototype.query and Connection.prototype.execute. This has a few fragility concerns in today's ecosystem:

• Runtime lock-in: both RITM and IITM rely on Node.js-specific module loader internals (Module._resolveFilename, module.register()). They don't work on Bun or Deno, which implement the Node.js API surface but not the module loader internals.
• ESM fragility: IITM is built on Node.js's module customization hooks, which are still evolving and have been a persistent source of breakage in the OTEL JS ecosystem.
• Initialization ordering: both require instrumentation to be set up before mysql2 is first require()'d / import'd. Get the order wrong and instrumentation silently does nothing, which is very hard to debug in production.
• Bundling and Externalization: Users have to ensure their instrumented modules are externalized, which is becoming very difficult to guarantee with more and more frameworks bundling server-side code into single executables, binaries, or deployment files.

If mysql2 emits structured events through TracingChannel, instrumentation libraries become subscribers, not patches. Each tool listens independently with no ordering concerns, no clobbering, and no internal API dependency.

Backward Compatability

Zero-cost when no subscribers are registered — hasSubscribers is checked before constructing any context objects. Silently skipped on Node.js versions where TracingChannel is unavailable (e.g. Node 18).

const tc = ('getBuiltinModule' in process)
  ? process.getBuiltinModule('node:diagnostics_channel')?.tracingChannel
  : undefined

Prior Art

This approach follows the same pattern already adopted or in progress by other major libraries:

• undici (Node.js core) — ships TracingChannel support since Node 20.12: undici:request
• node-redis — redis/node-redis#3195 (node-redis:command, node-redis:connect)
• ioredis — redis/ioredis#2089 (ioredis:command, ioredis:connect)
• pg / pg-pool — brianc/node-postgres#3624 (pg:query, pg:connection, pg:pool:connect)

I'm happy to help spec this and PR it.