feat: extend TracingChannel coverage to the callback API

The callback branches of query/batch/execute/bulk on Request, prepare
and execute on PreparedStatement, and connect on ConnectionPool were
previously invisible to TracingChannel subscribers, forcing consumers
to migrate to the promise API just to get observability.

Add a traceCallback helper alongside tracePromise in lib/diagnostics
that wraps Node's TracingChannel#traceCallback with the same
hasSubscribers fast path. Route each callback branch through it so
subscribers see the same start / end / asyncStart / asyncEnd / error
sub-events regardless of which API style the caller chose — no
branching required on the subscriber side.

Internal requests (sp_prepare, sp_execute, sp_unprepare) continue to
be suppressed via _internal; Request exposes a _tracedCallback mirror
of _tracedPromise to keep that gate symmetric. Stream-mode
PreparedStatement.execute without a user callback falls through
untraced because there is no async boundary for traceCallback to hook
— streaming consumers get lifecycle via Request events instead.

Update the README note that said the promise API was the only traced
path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dhensby

README.md

@@ -2265,7 +2265,7 @@ TracingChannel contexts include identifiers (`requestId`, `poolId`), operation d
 
 > **Note on identifiers:** `connectionId`, `poolId`, `requestId`, `transactionId`, and `preparedStatementId` are monotonically increasing integers scoped to the current node process. They are not stable across restarts and cannot be used to correlate activity across processes.
 
-> **Note:** TracingChannel instrumentation is active on the **promise** API. If you use the callback API, TracingChannel events will not fire for those calls. Point-event channels (connection, transaction, pool lifecycle) fire regardless of API style.
+> **Note:** TracingChannel instrumentation fires for both the promise and callback APIs. The callback API is traced via Node's `TracingChannel#traceCallback`, which emits the same `start` / `end` / `asyncStart` / `asyncEnd` / `error` sub-events as the promise path, so subscribers do not need to branch by API style. Point-event channels (connection, transaction, pool lifecycle) likewise fire regardless of API style.
 
 ### Point-event channels
 

lib/base/connection-pool.js

@@ -8,7 +8,7 @@ const { IDS } = require('../utils')
 const ConnectionError = require('../error/connection-error')
 const shared = require('../shared')
 const { MSSQLError } = require('../error')
-const { CHANNELS, tracePromise, publish } = require('../diagnostics')
+const { CHANNELS, tracePromise, traceCallback, publish } = require('../diagnostics')
 
 /**
  * Class ConnectionPool.
@@ -440,7 +440,16 @@ class ConnectionPool extends EventEmitter {
 
   connect (callback) {
     if (typeof callback === 'function') {
-      this._connect(callback)
+      traceCallback(CHANNELS.TRACE_CONNECT, this._connect, 0, () => ({
+        server: this.config.server,
+        port: this.config.port,
+        database: this.config.database,
+        poolId: IDS.get(this),
+        poolConfig: {
+          min: (this.config.pool && this.config.pool.min) || 0,
+          max: (this.config.pool && this.config.pool.max) || 10
+        }
+      }), this, [callback])
       return this
     }
 

lib/base/prepared-statement.js

@@ -7,7 +7,7 @@ const globalConnection = require('../global-connection')
 const { TransactionError, PreparedStatementError } = require('../error')
 const shared = require('../shared')
 const { TYPES, declare } = require('../datatypes')
-const { CHANNELS, tracePromise, publish } = require('../diagnostics')
+const { CHANNELS, tracePromise, traceCallback, publish } = require('../diagnostics')
 
 /**
  * Class PreparedStatement.
@@ -195,7 +195,12 @@ class PreparedStatement extends EventEmitter {
 
   prepare (statement, callback) {
     if (typeof callback === 'function') {
-      this._prepare(statement, callback)
+      traceCallback(CHANNELS.TRACE_PREPARED_STATEMENT_PREPARE, this._prepare, 1, () => ({
+        statement: statement || this.statement,
+        parameters: Object.keys(this.parameters),
+        preparedStatementId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this, [statement, callback])
       return this
     }
 
@@ -285,7 +290,19 @@ class PreparedStatement extends EventEmitter {
 
   execute (values, callback) {
     if (this.stream || (typeof callback === 'function')) {
-      return this._execute(values, callback)
+      if (typeof callback !== 'function') {
+        // Stream mode without a callback: no async boundary for traceCallback
+        // to hook — fall through to the untraced call. Subscribers interested
+        // in streaming completion should listen to Request events.
+        return this._execute(values, callback)
+      }
+      return traceCallback(CHANNELS.TRACE_PREPARED_STATEMENT_EXECUTE, this._execute, 1, () => ({
+        statement: this.statement,
+        parameters: Object.keys(this.parameters),
+        handle: this._handle,
+        preparedStatementId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this, [values, callback])
     }
 
     return tracePromise(CHANNELS.TRACE_PREPARED_STATEMENT_EXECUTE, () => {

lib/base/request.js

@@ -8,7 +8,7 @@ const globalConnection = require('../global-connection')
 const { RequestError, ConnectionError } = require('../error')
 const { TYPES } = require('../datatypes')
 const shared = require('../shared')
-const { CHANNELS, tracePromise, publish } = require('../diagnostics')
+const { CHANNELS, tracePromise, traceCallback, publish } = require('../diagnostics')
 
 /**
  * Class Request.
@@ -231,6 +231,13 @@ class Request extends EventEmitter {
     return tracePromise(channel, fn, contextFactory)
   }
 
+  _tracedCallback (channel, contextFactory, fn, position, args) {
+    if (this._internal) {
+      return fn.apply(this, args)
+    }
+    return traceCallback(channel, fn, position, contextFactory, this, args)
+  }
+
   /**
    * Execute the SQL batch.
    *
@@ -245,7 +252,11 @@ class Request extends EventEmitter {
     this.rowsAffected = 0
 
     if (typeof callback === 'function') {
-      this._batch(batch, (err, recordsets, output, rowsAffected) => {
+      this._tracedCallback(CHANNELS.TRACE_BATCH, () => ({
+        command: batch,
+        requestId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this._batch, 1, [batch, (err, recordsets, output, rowsAffected) => {
         if (this.stream) {
           if (err) this.emit('error', err)
           err = null
@@ -263,7 +274,7 @@ class Request extends EventEmitter {
           output,
           rowsAffected
         })
-      })
+      }])
       return this
     }
 
@@ -344,7 +355,12 @@ class Request extends EventEmitter {
     if (this.arrayRowMode === null && this.parent) this.arrayRowMode = this.parent.config.arrayRowMode
 
     if (this.stream || typeof callback === 'function') {
-      this._bulk(table, options, (err, rowsAffected) => {
+      this._tracedCallback(CHANNELS.TRACE_BULK, () => ({
+        table: table.path || table.name,
+        rowCount: table.rows ? table.rows.length : 0,
+        requestId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this._bulk, 2, [table, options, (err, rowsAffected) => {
         if (this.stream) {
           if (err) this.emit('error', err)
           return this.emit('done', {
@@ -356,7 +372,7 @@ class Request extends EventEmitter {
         callback(null, {
           rowsAffected
         })
-      })
+      }])
       return this
     }
 
@@ -456,7 +472,12 @@ class Request extends EventEmitter {
     this.rowsAffected = 0
 
     if (typeof callback === 'function') {
-      this._query(command, (err, recordsets, output, rowsAffected, columns) => {
+      this._tracedCallback(CHANNELS.TRACE_QUERY, () => ({
+        command,
+        parameters: this._getParameterNames(),
+        requestId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this._query, 1, [command, (err, recordsets, output, rowsAffected, columns) => {
         if (this.stream) {
           if (err) this.emit('error', err)
           err = null
@@ -476,7 +497,7 @@ class Request extends EventEmitter {
         }
         if (this.arrayRowMode) result.columns = columns
         callback(null, result)
-      })
+      }])
       return this
     }
 
@@ -552,7 +573,12 @@ class Request extends EventEmitter {
     this.rowsAffected = 0
 
     if (typeof callback === 'function') {
-      this._execute(command, (err, recordsets, output, returnValue, rowsAffected, columns) => {
+      this._tracedCallback(CHANNELS.TRACE_EXECUTE, () => ({
+        procedure: command,
+        parameters: this._getParameterNames(),
+        requestId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this._execute, 1, [command, (err, recordsets, output, returnValue, rowsAffected, columns) => {
         if (this.stream) {
           if (err) this.emit('error', err)
           err = null
@@ -574,7 +600,7 @@ class Request extends EventEmitter {
         }
         if (this.arrayRowMode) result.columns = columns
         callback(null, result)
-      })
+      }])
       return this
     }
 

lib/diagnostics.js

@@ -105,6 +105,30 @@ function tracePromise (name, fn, contextFactory) {
   return fn()
 }
 
+/**
+ * Trace a callback-style async operation using a TracingChannel.
+ *
+ * When subscribers are active, delegates to TracingChannel.traceCallback,
+ * which replaces the callback at `position` in `args` with a wrapped
+ * version that publishes to start/end/asyncStart/asyncEnd/error. When
+ * no subscribers are active, calls `fn` directly with zero overhead.
+ *
+ * @param {string} name - TracingChannel name (one of CHANNELS.TRACE_*)
+ * @param {Function} fn - The function to call (receives callback at `position`)
+ * @param {number} position - Index of the callback within `args`
+ * @param {Function} contextFactory - Factory function returning the context object
+ * @param {*} thisArg - `this` binding for fn
+ * @param {Array} args - Arguments to pass to fn (includes the callback at `position`)
+ * @returns {*} The return value of fn
+ */
+function traceCallback (name, fn, position, contextFactory, thisArg, args) {
+  const channel = tracingChannels[name]
+  if (tracingChannelHasSubscribers(channel)) {
+    return channel.traceCallback(fn, position, contextFactory(), thisArg, ...args)
+  }
+  return fn.apply(thisArg, args)
+}
+
 /**
  * Publish a point event on a named channel.
  *
@@ -124,5 +148,6 @@ module.exports = {
   CHANNELS,
   tracingChannels,
   tracePromise,
+  traceCallback,
   publish
 }

test/common/diagnostics.js

@@ -371,4 +371,117 @@ describe('Diagnostics Channel', () => {
       }
     })
   })
+
+  // Exercise the callback API through TracingChannel#traceCallback, which
+  // shares the sub-event channels (start/asyncEnd/error/...) with
+  // tracePromise — subscribers should not need to branch by API style.
+  describe('Callback API tracing', () => {
+    const sql = require('../../')
+
+    function collectTraces (tracingChannel) {
+      const events = []
+      const handlers = {
+        start: (ctx) => events.push({ event: 'start', ctx }),
+        end: (ctx) => events.push({ event: 'end', ctx }),
+        asyncStart: (ctx) => events.push({ event: 'asyncStart', ctx }),
+        asyncEnd: (ctx) => events.push({ event: 'asyncEnd', ctx }),
+        error: (ctx) => events.push({ event: 'error', ctx })
+      }
+      tracingChannel.subscribe(handlers)
+      return {
+        events,
+        stop () { tracingChannel.unsubscribe(handlers) }
+      }
+    }
+
+    it('request.query(cb) emits TRACE_QUERY start/asyncEnd with context', (done) => {
+      const req = new sql.Request()
+      req._query = (cmd, cb) => setImmediate(cb, null, [[{ x: 1 }]], {}, 1)
+      req.input('id', sql.Int, 42)
+
+      const tc = tracingChannels[CHANNELS.TRACE_QUERY]
+      const { events, stop } = collectTraces(tc)
+      req.query('SELECT @id', (err, result) => {
+        assert.ifError(err)
+        assert.ok(result)
+        // asyncEnd fires after this callback returns, so defer the check.
+        setImmediate(() => {
+          try {
+            const starts = events.filter(e => e.event === 'start')
+            const asyncEnds = events.filter(e => e.event === 'asyncEnd')
+            assert.strictEqual(starts.length, 1)
+            assert.strictEqual(asyncEnds.length, 1)
+            assert.strictEqual(starts[0].ctx.command, 'SELECT @id')
+            assert.deepStrictEqual(starts[0].ctx.parameters, ['id'])
+            done()
+          } catch (e) {
+            done(e)
+          } finally {
+            stop()
+          }
+        })
+      })
+    })
+
+    it('request.query(cb) emits TRACE_QUERY error on driver failure', (done) => {
+      const req = new sql.Request()
+      const boom = new Error('boom')
+      req._query = (cmd, cb) => setImmediate(cb, boom)
+
+      const tc = tracingChannels[CHANNELS.TRACE_QUERY]
+      const { events, stop } = collectTraces(tc)
+      req.query('SELECT 1', (err) => {
+        try {
+          assert.strictEqual(err, boom)
+          const errors = events.filter(e => e.event === 'error')
+          assert.strictEqual(errors.length, 1)
+          assert.strictEqual(errors[0].ctx.error, boom)
+          done()
+        } catch (e) {
+          done(e)
+        } finally {
+          stop()
+        }
+      })
+    })
+
+    it('callback path honours the _internal flag', (done) => {
+      const req = new sql.Request()
+      req._internal = true
+      req._query = (cmd, cb) => setImmediate(cb, null, [[]], {}, 0)
+
+      const tc = tracingChannels[CHANNELS.TRACE_QUERY]
+      const { events, stop } = collectTraces(tc)
+      req.query('SELECT 1', () => {
+        try {
+          assert.strictEqual(events.length, 0)
+          done()
+        } catch (e) {
+          done(e)
+        } finally {
+          stop()
+        }
+      })
+    })
+
+    it('request.execute(cb) emits TRACE_EXECUTE', (done) => {
+      const req = new sql.Request()
+      req._execute = (cmd, cb) => setImmediate(cb, null, [[]], {}, 0, 0)
+
+      const tc = tracingChannels[CHANNELS.TRACE_EXECUTE]
+      const { events, stop } = collectTraces(tc)
+      req.execute('sp_test', () => {
+        try {
+          const starts = events.filter(e => e.event === 'start')
+          assert.strictEqual(starts.length, 1)
+          assert.strictEqual(starts[0].ctx.procedure, 'sp_test')
+          done()
+        } catch (e) {
+          done(e)
+        } finally {
+          stop()
+        }
+      })
+    })
+  })
 })