feat: add diagnostics_channel support

[dhensby]

Summary

Adds diagnostics_channel integration to node-mssql, enabling observability tooling (OpenTelemetry, custom metrics, logging) to subscribe to library events with near-zero overhead when not in use.

Inspired by node-redis#3195.

TracingChannels (8)

Async operation tracing via dc.tracingChannel() — provides start/end/asyncStart/asyncEnd/error lifecycle events for both the promise and callback APIs:

• mssql:query — request.query()
• mssql:batch — request.batch()
• mssql:execute — request.execute()
• mssql:bulk — request.bulk()
• mssql:connect — pool.connect()
• mssql:pool:acquire — connection acquisition from pool (measures wait/saturation)
• mssql:prepared-statement:prepare — ps.prepare()
• mssql:prepared-statement:execute — ps.execute()

Point-event channels (10)

Single events at state transitions:

• mssql:connection:acquire / release
• mssql:connection:create / destroy
• mssql:pool:close
• mssql:transaction:begin / commit / rollback
• mssql:request:cancel
• mssql:prepared-statement:unprepare

Design decisions

• Node.js >=18.19.0 minimum — required for dc.tracingChannel(); includes polyfill for TracingChannel.hasSubscribers (added in Node 22)
• Both promise and callback APIs are instrumented via tracePromise() and traceCallback() respectively
• Context factories — all trace contexts and point-event messages use factory callbacks, so there is zero object allocation when no subscribers are active
• Zero overhead when no subscribers — hasSubscribers check gates all work
• Internal request suppression — framework-generated requests (sp_prepare, sp_execute, sp_unprepare) are marked _internal = true and excluded from tracing
• No parameter values in trace contexts — only parameter names; SQL text is included but documented with redaction guidance
• XACT_ABORT auto-rollback tracked in tedious driver via transaction:rollback with aborted: true
• CHANNELS exported as a frozen object of string constants for minimal semver surface
• getPoolId() hoisted to lib/utils.js as a shared utility
• Pool close publishes on both success and failure paths, with optional error in the payload
• Transaction events include both numeric isolationLevel and human-readable isolationLevelName
• Prepared-statement channels namespaced under mssql:prepared-statement:* for consistency

Breaking changes

• Minimum Node.js version bumped from >=18 to >=18.19.0

Files changed (14)

File	Change
lib/diagnostics.js	New — core infrastructure (CHANNELS, tracingChannels, tracePromise, traceCallback, publish)
lib/base/request.js	Instrument query/batch/execute/bulk (promise + callback), cancel event, _internal flag
lib/base/connection-pool.js	Instrument connect, acquire (TracingChannel), release, close events
lib/base/transaction.js	Publish begin/commit/rollback events with isolation level
lib/base/prepared-statement.js	Instrument prepare/execute (TracingChannel), unprepare event, mark internal requests
lib/tedious/connection-pool.js	Publish connection:create / connection:destroy
lib/msnodesqlv8/connection-pool.js	Publish connection:create / connection:destroy
lib/tedious/transaction.js	Publish transaction:rollback on XACT_ABORT auto-abort
lib/base/index.js	Export CHANNELS
lib/utils.js	Add shared getPoolId() helper
package.json	Bump engines.node to >=18.19.0
README.md	Diagnostics Channel documentation section
test/common/diagnostics.js	New — 27 unit tests
test/common/unit.js	Include diagnostics test file

Test coverage

74 total unit tests passing (47 existing + 27 new diagnostics tests):

• Channel constant exports and structure
• TracingChannel instance creation
• tracePromise / traceCallback zero-overhead when no subscribers
• Context factory lazy evaluation
• TracingChannel lifecycle events (start, asyncEnd, error)
• traceCallback lifecycle events
• publish zero-overhead and message delivery
• End-to-end instrumentation verification (Request, Transaction, PreparedStatement)
• CHANNELS accessibility via require("mssql")
• _internal flag default value

[Copilot]

Pull request overview

Adds diagnostics_channel instrumentation to node-mssql so external observability tooling can subscribe to query/pool/transaction/prepared-statement lifecycle events (TracingChannels + point events) with minimal overhead when unused, and bumps the minimum supported Node.js version to enable dc.tracingChannel().

Changes:

• Introduces lib/diagnostics.js (CHANNELS constants, tracing/publish helpers) and exports CHANNELS from the public module surface.
• Instruments core public APIs (Request/ConnectionPool/Transaction/PreparedStatement) plus driver pools/transactions to emit tracing + point events.
• Adds unit tests and README documentation for the new channels and payloads; bumps engines.node to >=18.19.0.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
lib/diagnostics.js	New diagnostics_channel infrastructure (channels + helpers).
lib/base/request.js	Adds tracing/publish hooks around query/batch/execute/bulk and cancel; introduces _internal.
lib/base/connection-pool.js	Adds tracing for connect/acquire and point events for acquire/release/close.
lib/base/transaction.js	Publishes begin/commit/rollback point events incl. isolation level info.
lib/base/prepared-statement.js	Adds tracing for prepare/execute, point event for unprepare, marks internal requests.
lib/tedious/connection-pool.js	Publishes connection create/destroy events for tedious driver connections.
lib/msnodesqlv8/connection-pool.js	Publishes connection create/destroy events for msnodesqlv8 driver connections.
lib/tedious/transaction.js	Emits rollback event on XACT_ABORT auto-abort.
lib/utils.js	Adds getPoolId() helper for consistent pool identification in payloads.
lib/base/index.js	Exports CHANNELS from the main module surface.
package.json	Bumps Node engine requirement to >=18.19.0.
README.md	Documents Diagnostics Channel usage, channel list, and example OTel spans.
test/common/diagnostics.js	New unit tests covering CHANNELS, helpers, and integration wiring.
test/common/unit.js	Includes the new diagnostics unit test suite.

[github-actions]

🎉 This PR is included in version 12.4.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀