newrelic 13.6.0 → 13.6.2

package/NEWS.md

@@ -1,3 +1,24 @@
+### v13.6.2 (2025-10-29)
+
+#### Bug fixes
+
+* Updated express instrumentation to properly instrument an array of middleware defined on a route ([#3473](https://github.com/newrelic/node-newrelic/pull/3473)) ([e383c4e](https://github.com/newrelic/node-newrelic/commit/e383c4efc7171f02aef41d6c657455338b4b7258))
+
+#### Documentation
+
+* documented how to use the subscriber based instrumentation ([#3432](https://github.com/newrelic/node-newrelic/pull/3432)) ([3b3ab72](https://github.com/newrelic/node-newrelic/commit/3b3ab72eee3b4c1a12592d92eab59da2a48b1f46))
+* Updated compatibility report ([#3471](https://github.com/newrelic/node-newrelic/pull/3471)) ([964543b](https://github.com/newrelic/node-newrelic/commit/964543bae1a7c1fd5af32f02ba40d4bf68737d11))
+
+### v13.6.1 (2025-10-28)
+
+#### Bug fixes
+
+* Updated middleware wrapper to not wrap handler if it is not a function ([#3469](https://github.com/newrelic/node-newrelic/pull/3469)) ([c702689](https://github.com/newrelic/node-newrelic/commit/c702689a6e73756f6b3ad39706a33874fbd6da73))
+
+#### Documentation
+
+* Updated compatibility report ([#3466](https://github.com/newrelic/node-newrelic/pull/3466)) ([5853657](https://github.com/newrelic/node-newrelic/commit/5853657a63dc75481fc6598c10afd208391f525b))
+
 ### v13.6.0 (2025-10-27)
 
 #### Features
@@ -8000,3 +8021,4 @@ Special thanks to Ryan Copley (@RyanCopley) for the contribution.
 
 
 
+

package/lib/subscribers/README.md

@@ -0,0 +1,101 @@
+# Subscriber-based Instrumentation
+
+As of v13.2.0, we have begun to refactor our traditional instrumentation (`Shim`-based monkey-patching) to instead subscribe to events emitted by Node's [`diagnostic_channel TracingChannel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel). This is done through [`@apm-js-collab/tracing-hooks`](https://github.com/apm-js-collab/tracing-hooks), a helper for [`orchestrion-js`](https://github.com/apm-js-collab/orchestrion-js) which injects the relevant tracing channels into the instrumented package. We then define a `Subscriber` that listens to these channels for specific events (`asyncEnd`, `asyncStart`, `start`, `end`, and/or `error`) and record what we need from the event data and context (which is preserved through `AsyncLocalStorage`).
+
+## How to Implement
+
+Like `Shim`-based instrumentation, subscriber-based instrumentation largely relies on the specific way the package you're instrumenting is written. However, all packages will follow the below template/guidelines.
+
+### Disable Shim-based Instrumentation
+
+1. While you are testing your new instrumentation, it's important that you're not also testing the old instrumentation. However, you likely want to keep the old instrumentation around while you're refactoring for reference. The easiest way to do this is to just remove the instrumentation reference in `lib/instrumentations.js`.
+2. When you are done refactoring, make sure to delete all files in `lib/instrumentation/<package_name>` (or `lib/instrumentation/<package_name>.js`), the tests in `test/unit/instrumentation/<package_name> `that rely on `Shim`-based wrapping, and the instrumentation reference in `instrumentations.js` if you haven't already.
+
+### Instrumentation Config
+
+Now, it is time to look at the internals of the package you're instrumenting. Again, the `Shim`-based instrumentation you're replacing should be helpful here to get the gist of the package internals.
+
+1. Create a folder within `lib/subscribers` with the name of the package. If the package is not a new instrumentation, use the same name as the one in `test/versioned`. If it is a new instrumentation and the package name is exceptionally long or complicated or is prefixed with  `@`, you may provide a shortened version (e.g. `@modelcontextprotocol/sdk `->`mcp-sdk `). Remember to name the versioned test folder with the same name (`test/versioned/<package_name|shortened_package_name>`).
+2. Create a `config.js` within that folder.
+3. Add a reference to the new config file in [`lib/subscriber-configs.js`](../subscriber-configs.js):
+   1. ```javascript
+      ...require('./subscribers/<package_name>/config')
+      ```
+4. Identify one function to start with and find where this function lives in the package i.e. the relative file path.
+5. Once you have found where the function you're instrumenting is, you need to determine how it is defined in [AST](https://astexplorer.net/), so that `orchestrion` can properly wrap it. You can then add the proper instrumentation object to your `config.js`.
+
+#### Config Template
+
+```javascript
+// in lib/subscribers/<package_name>/config.js
+
+const config = {
+  path: './<package_name>/<subscriber_name>.js',
+  instrumentations: [
+    {
+      /**
+       * By convention, we prefix channelNames with `nr_` and include at least the expressionName or methodName.
+       * It could also contain the moduleName or className to further differentiate between subscribers.
+       */
+      channelName: 'nr_functionName',
+      /**
+       * <version_range> should be the same as the old instrumentation.
+       * However, you may need to break apart that range across different configs
+       * because code can differ from version to version.
+       *
+       * <relative_path_to_file> is the relative path from the instrumented package
+       * to the file that contains the code that you want to instrument
+       */
+      module: { name: '<package_name>', versionRange: '<version_range>', filePath: '<relative_path_to_file>' },
+      functionQuery: {
+        className: 'ClassName',
+        methodName: 'methodName',
+        // If the function is `async`, specify `Async` here. Callback functions are typically `Sync`.
+        kind: 'Sync' | 'Async'
+      },
+      // OR
+      // if not a Class
+      functionQuery: {
+        moduleName: 'ModuleName',
+        expressionName: 'expressionName',
+        kind: 'Sync' | 'Async'
+      },
+      // OR
+      // if the module is not defined
+      functionQuery: {
+        expressionName: 'expressionName',
+        kind: 'Sync' | 'Async'
+      }
+    }
+    /**
+     * If you need to use the same instrumentation/subscriber for differently structured code
+     * (e.g. an older version of the package uses moduleName/expressionName, but now the
+     * same function is className/methodName), you'd add another instrumentation object
+     * to the array of `instrumentations`.
+     */
+  ]
+}
+
+module.exports = {
+  // Note: config(s) must be in an array, even if there's just one
+  '<package_name>': [
+    config
+  ]
+}
+```
+
+### Creating the Subscribers
+
+Now that you have the config specified for the function that you are instrumenting, you'll then need to create a subscriber for it. All subscribers should at least inherit from the base [`Subscriber`](./base.js) with the exception of subscribers that do not rely on `orchestrion` to create their tracing channels (they inherit from the `node:diagnostics_channel` `Subscriber` in [`dc-base.js`](./dc-base.js)).
+
+#### Datastore Subscribers
+
+For datastore queries, inherit from `DbQuerySubscriber`. For datastore operations, inherit from `DbOperationSubscriber`.
+
+#### Messaging Subscribers
+
+For messaging queues, inherit from `MessageConsumerSubscriber` or `MessageProducerSubscriber.`
+
+#### Propagation Subscriber
+
+Many packages are written in a way that causes `AsyncLocalStorage` to lose context. A common instance of this is multiple nestled callbacks. To solve this, create `PropagationSubscriber`s for inner functions within the one you are instrumenting. You may have to experiment a few times to know which function is losing context; in most cases, you should only need one `PropagationSubscriber` to support another subscriber.

package/lib/subscribers/amqplib/consume.js

@@ -3,10 +3,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-const MessageConsumer = require('../message-consumer')
+const MessageConsumerSubscriber = require('../message-consumer')
 const { getParameters, getParametersFromMessage, TEMP_RE } = require('./utils')
 
-class ConsumeSubscriber extends MessageConsumer {
+class ConsumeSubscriber extends MessageConsumerSubscriber {
   constructor({ agent, logger, channelName = 'nr_consume' }) {
     super({ agent, logger, packageName: 'amqplib', channelName, system: 'RabbitMQ', type: 'Exchange', callback: 1, transport: 'AMQP' })
     this.segmentName = 'amqplib.Channel#consume'

package/lib/subscribers/application-logs.js

@@ -4,11 +4,15 @@
  */
 
 const Subscriber = require('./base')
-const { isApplicationLoggingEnabled, isLocalDecoratingEnabled, isLogForwardingEnabled, isMetricsEnabled, createModuleUsageMetric, incrementLoggingLinesMetrics } = require('../util/application-logging')
+const { isApplicationLoggingEnabled,
+  isLocalDecoratingEnabled,
+  isLogForwardingEnabled,
+  isMetricsEnabled, createModuleUsageMetric,
+  incrementLoggingLinesMetrics } = require('../util/application-logging')
 
 class ApplicationLogsSubscriber extends Subscriber {
-  constructor({ agent, logger, packageName, channelName, }) {
-    super({ agent, logger, packageName, channelName, })
+  constructor({ agent, logger, packageName, channelName }) {
+    super({ agent, logger, packageName, channelName })
     this.requireActiveTx = false
     this.libMetricCreated = false
   }

package/lib/subscribers/base.js

@@ -38,20 +38,31 @@ const ArrayPrototypeSplice = makeCall(Array.prototype.splice)
  * register handlers for. For any name in the set, a corresponding method
  * must exist on the subscriber instance. The method will be passed the
  * event object. Possible event names are `start`, `end`, `asyncStart`,
- * `asyncEnd`, and `error`. @link https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel
- * @property {boolean} [opaque=false] If true, any children segments will not be created
- * @property {boolean} [internal=false] If true, any children segments from the same library will not be created
+ * `asyncEnd`, and `error`.
+ *
+ *  See {@link https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel}
+ * @property {boolean} [opaque=false] If true, any children segments will not be created.
+ * @property {boolean} [internal=false] If true, any children segments from the same library
+ * will not be created.
  * @property {string} [prefix='orchestrion:'] String to prepend to diagnostics
  * channel event names. This provides a namespace for the events we are
  * injecting into a module.
- * @property {boolean} [requireActiveTx=true] If true, the subscriber will only handle events when there is an active transaction.
- * @property {boolean} [propagateContext=false] If true, it will bind `asyncStart` to the store and re-propagate the active context. It will also attach the `transaction` to the event in `start.bindStore`. This is used for functions that queue async code and context is lost.
- * @property {string} id A unique identifier for the subscriber, combining the prefix, package name, and channel name.
+ * @property {boolean} [requireActiveTx=true] If true, the subscriber will only handle events
+ * when there is an active transaction.
+ * @property {boolean} [propagateContext=false] If true, it will bind `asyncStart` to the store
+ * and re-propagate the active context. It will also attach the `transaction` to the event in
+ * `start.bindStore`. This is used for functions that queue async code and context is lost.
+ * @property {string} id A unique identifier for the subscriber, combining the prefix, package
+ * name, and channel name.
  * @property {TracingChannel} channel The tracing channel instance this subscriber will be monitoring.
  * @property {AsyncLocalStorage} store The async local storage instance used for context management.
- * @property {number} callback position of callback if it needs to be wrapped for instrumentation. -1 means last argument
+ * @property {number} [callback=null] Position of callback if it needs to be wrapped for instrumentation.
+ * -1 means last argument.
  */
 class Subscriber {
+  /**
+   * @param {SubscriberParams} params the subscriber constructor params
+   */
   constructor({ agent, logger, packageName, channelName }) {
     this.agent = agent
     this.logger = logger.child({ component: `${packageName}-subscriber` })
@@ -121,15 +132,15 @@ class Subscriber {
 
   /**
    * Wraps an event emitter and runs the wrap in the new context
-   * If the event is `end` or `error` it'll touch the active segment
+   * If the event is `end` or `error`, it'll touch the active segment.
    *
    * @param {object} params to function
    * @param {Array} params.args arguments to function
    * @param {number} params.index index of argument to wrap
-   * @param {string} params.name name of emit function
+   * @param {string} [params.name] name of emit function, defaults to 'emit'
    * @param {Context} params.ctx context to bind wrapped emit to
    */
-  wrapEventEmitter({ args, index, name, ctx }) {
+  wrapEventEmitter({ args, index, name = 'emit', ctx }) {
     const orig = args[index][name]
     const self = this
     function wrapEmit(...emitArgs) {
@@ -148,7 +159,7 @@ class Subscriber {
    * If the segment is successfully created, it will be started and added to the context.
    * @param {object} params - Parameters for creating the segment
    * @param {string} params.name - The name of the segment
-   * @param {object} params.recorder - Optional recorder for the segment
+   * @param {object} [params.recorder] - Optional recorder for the segment
    * @param {Context} params.ctx - The context containing the parent segment and transaction
    * @returns {Context} - The updated context with the new segment or existing context if segment creation fails
    */
@@ -191,8 +202,8 @@ class Subscriber {
   }
 
   /**
-   * Not all subscribers need change the context on `start`.
-   * This is defined on base to fulfill those use cases
+   * Not all subscribers need to change the context on an event.
+   * This is defined on base to fulfill those use cases.
    * @param {object} data event passed to handler
    * @param {Context} ctx context passed to handler
    * @returns {Context} either new context or existing

package/lib/subscribers/db-operation.js

@@ -9,6 +9,9 @@ const { DB } = require('../metrics/names')
 
 /**
  * Subscriber for database operation events e.g. `connect`.
+ *
+ * @property {string} operation The name of the database operation.
+ * Used to name the segment created for this operation.
  */
 class DbOperationSubscriber extends DbSubscriber {
   /**

package/lib/subscribers/db-query.js

@@ -9,7 +9,24 @@ const { DB } = require('../metrics/names')
 const ParsedStatement = require('../db/parsed-statement')
 const parseSql = require('../db/query-parsers/sql')
 
+/**
+ * Defines a subscriber for database queries.
+ *
+ * @property {string} queryString Must be set by any class that extends this
+ * one prior to this class's `.handler` method being invoked. It represents
+ * the statement being sent to the database.
+ * @property {boolean} [isBatch] Set to true if this subscriber is for batch queries.
+ */
 class DbQuerySubscriber extends DbSubscriber {
+  /**
+   * On an event, this handler will create a segment with the name
+   * `{DB.STATEMENT}/{DB_SYSTEM}/{COLLECTION}/{OPERATION}`.
+   * Other than `DB.STATEMENT` which is a constant, these values
+   * are extracted from `this.queryString`.
+   * @param {object} data event data
+   * @param {Context} ctx the context
+   * @returns {Context} the updated context with the new segment
+   */
   handler(data, ctx) {
     const queryString = this.queryString
     const parsed = this.parseQueryString(queryString)

package/lib/subscribers/db.js

@@ -7,7 +7,25 @@ const Subscriber = require('./base')
 const { ALL, DB } = require('../metrics/names')
 const urltils = require('../util/urltils')
 
+/**
+ * @property {object} parameters Must be set by subclasses prior to invoking
+ * the `addAttributes` method. Should contain the following keys:
+ * - `host`: The database host.
+ * - `database_name`: The name of the database.
+ * - `port_path_or_id`: The database port, path, or ID.
+ * @property {string} system The database system being used (e.g., MySQL, MongoDB).
+ */
 class DbSubscriber extends Subscriber {
+  /**
+   * @param {object} params constructor params object
+   * @param {object} params.agent A New Relic Node.js agent instance.
+   * @param {object} params.logger An agent logger instance.
+   * @param {string} params.packageName The package name being instrumented.
+   * This is what a developer would provide to the `require` function.
+   * @param {string} params.channelName A unique name for the diagnostics channel
+   * that will be created and monitored.
+   * @param {string} params.system The database system being used (e.g., MySQL, MongoDB).
+   */
   constructor({ agent, logger, packageName, channelName, system }) {
     super({ agent, logger, packageName, channelName })
     this.system = system
@@ -29,8 +47,12 @@ class DbSubscriber extends Subscriber {
     return this.config.datastore_tracer.database_name_reporting.enabled
   }
 
+  /**
+   * Adds `this.parameters` to the active segment.
+   * @param {object} segment the current segment
+   */
   addAttributes(segment) {
-    for (let [key, value] of Object.entries(this.parameters)) {
+    for (let [key, value] of Object.entries(this.parameters ?? {})) {
       if (this.instanceKeys.includes(key) && !this.instanceReporting) {
         continue
       }

package/lib/subscribers/express/route.js

@@ -33,6 +33,16 @@ class ExpressRouteSubscriber extends MiddlewareSubscriber {
         // express could have multiple routers, wrap them all
         for (let i = 0; i < routeArgs.length; i++) {
           const routeHandler = routeArgs[i]
+          // express supports an array of middlewares as well when defining route
+          // wrap each handler and reassign to args
+          if (Array.isArray(routeHandler)) {
+            for (let j = 0; j < routeHandler.length; j++) {
+              const handler = routeHandler[j]
+              routeArgs[i][j] = self.wrapper.wrap({ handler })
+            }
+            continue
+          }
+
           let segmentName = null
           let route = null
           if (routeHandler.stack) {

package/lib/subscribers/express/use.js

@@ -23,12 +23,14 @@ class ExpressUseSubscriber extends MiddlewareSubscriber {
       fnIndex = 0
     }
     let segmentName = null
+    // sometimes route is undefined, default to `/` for segmentName only
+    const routeName = route || '/'
     // Pre v5 these were marked as `lazyrouter`
     // check for both
     if (fn.lazyrouter || fn.name === 'mounted_app') {
-      segmentName = `${this.wrapper.system}/Mounted App: ${route}`
+      segmentName = `${this.wrapper.system}/Mounted App: ${routeName}`
     } else if (fn.stack) {
-      segmentName = `${this.wrapper.system}/Router: ${route}`
+      segmentName = `${this.wrapper.system}/Router: ${routeName}`
       method = 'handle'
     }
 

package/lib/subscribers/message-consumer.js

@@ -10,10 +10,6 @@ const messageTransactionRecorder = require('#agentlib/metrics/recorders/message-
 const isString = require('#agentlib/util/is-string.js')
 
 /**
- * A message consumer does the following:
- *  1. Calling consume creates a segment if in an active transaction
- *  2. For every consumption, typically registered as a callback, it will create a transaction of type `message`, create a baseSegment, add both segment and trace attributes, and assign the `message-transaction` timeslice metrics
- *
  * @typedef {object} MessageConsumerParams
  * @property {object} agent A New Relic Node.js agent instance.
  * @property {object} logger An agent logger instance.
@@ -26,7 +22,16 @@ const isString = require('#agentlib/util/is-string.js')
  * @property {number} callback if consumer is callback based, indicates index of callback
  * @property {string} transport identifier of the transport(see Transaction.TRANSPORT_TYPES)
  */
-class MessageConsumer extends Subscriber {
+
+/**
+ * A message consumer does the following:
+ *  1. Calling consume creates a segment if in an active transaction
+ *  2. For every consumption, typically registered as a callback, it will create a transaction of type `message`, create a baseSegment, add both segment and trace attributes, and assign the `message-transaction` timeslice metrics
+ */
+class MessageConsumerSubscriber extends Subscriber {
+  /**
+   * @param {MessageConsumerParams} params constructor params
+   */
   constructor({ agent, logger, packageName, channelName, system, type, callback, transport }) {
     super({ agent, logger, packageName, channelName })
     this.system = system
@@ -143,4 +148,4 @@ class MessageConsumer extends Subscriber {
   }
 }
 
-module.exports = MessageConsumer
+module.exports = MessageConsumerSubscriber

package/lib/subscribers/message-producer.js

@@ -8,11 +8,7 @@ const Subscriber = require('./base')
 const genericRecorder = require('#agentlib/metrics/recorders/generic.js')
 
 /**
- *
- * Creates the segment for a message producer call. Injects appropriate DT/CAT
- * headers if enabled.
- *
- *  @typedef {object} MessageProducerParams
+ * @typedef {object} MessageProducerParams
  * @property {object} agent A New Relic Node.js agent instance.
  * @property {object} logger An agent logger instance.
  * @property {string} packageName The package name being instrumented.
@@ -22,7 +18,15 @@ const genericRecorder = require('#agentlib/metrics/recorders/generic.js')
  * @property {string} system canonical mapping of system(i.e. - Kafka, RabbitMq, SNS, SQS)
  * @property {string} type destinationType: Exchange, Queue, Topic
  */
+
+/**
+ * Creates the segment for a message producer call. Injects appropriate DT/CAT
+ * headers if enabled.
+ */
 class MessageProducerSubscriber extends Subscriber {
+  /**
+   * @param {MessageProducerParams} params constructor params
+   */
   constructor({ agent, logger, packageName, channelName, system, type }) {
     super({ agent, logger, packageName, channelName })
     this.system = system

package/lib/subscribers/meta-subscriber.js

@@ -7,9 +7,6 @@
 const Subscriber = require('./base')
 
 /**
- * Used to subscribe to many different events that have the same behavior around
- * segment creation.
- *
  * @typedef {object} MetaSubscriberParams
  * @property {object} agent A New Relic Node.js agent instance.
  * @property {object} logger An agent logger instance.
@@ -17,12 +14,22 @@ const Subscriber = require('./base')
  * This is what a developer would provide to the `require` function.
  * @property {string} channelName A unique name for the diagnostics channel
  * that will be created and monitored.
- * @property {Array} channels list of channels to construct new subscribers
- * @property {Array} events list of events to subscribe to new subscribers
- * @property {number} callback if consumer is callback based, indicates index of callback
+ * @property {string[]} channels list of channels to construct new subscribers
+ * @property {string[]} events list of events to subscribe to new subscribers
+ * @property {number} [callback=null] if consumer is callback based, indicates index of callback
+ */
+
+/**
+ * Used to subscribe to many different events that have the same behavior around
+ * segment creation.
+ *
+ * @example - ./amqplib/channel-model.js
  */
 class MetaSubscriber {
-  constructor({ agent, logger, packageName, channelName, channels, events, callback }) {
+  /**
+   * @param {MetaSubscriberParams} params constructor params
+   */
+  constructor({ agent, logger, packageName, channelName, channels, events, callback = null }) {
     this.config = agent.config
     this.packageName = packageName
     this.id = `orchestrion:${packageName}:${channelName}`

package/lib/subscribers/middleware-wrapper.js

@@ -59,8 +59,17 @@ class MiddlewareWrapper {
    */
   wrap({ handler, prefix, route, segmentName, nextIdx = -1 }) {
     const self = this
+    if (typeof handler !== 'function') {
+      this.logger.trace('Handler: %s is not a function, not wrapping.', handler)
+      return handler
+    }
+
     function wrappedHandler (...args) {
       const ctx = self.agent.tracer.getContext()
+      if (ctx?.transaction?.isActive() !== true) {
+        self.logger.trace('No active transaction, calling original function')
+        return handler.apply(this, args)
+      }
       const transaction = ctx?.transaction
       transaction.nameState.setPrefix(self.system)
       const { txInfo, errorWare, request } = self.extractTxInfo(args, route)

package/lib/subscribers/propagation.js

@@ -8,10 +8,21 @@ const Subscriber = require('./base')
 
 /**
  * This subscriber is purely for propagation of async context within the `asyncStart` event.
- * This will be typically used in a callback based scenario where there is async code getting scheduled
- * but not bound to the context.
+ * This will be typically used in a callback based scenario where there is async code getting
+ * scheduled but not bound to the context.
  */
 class PropagationSubscriber extends Subscriber {
+  /**
+   *
+   * @param {object} params constructor params
+   * @param {object} params.agent A New Relic Node.js agent instance.
+   * @param {object} params.logger An agent logger instance.
+   * @param {string} params.packageName The package name being instrumented.
+   * This is what a developer would provide to the `require` function.
+   * @param {string} params.channelName A unique name for the diagnostics channel
+   * that will be created and monitored.
+   * @param {number} params.callback position of callback if it needs to be wrapped for instrumentation. -1 means last argument
+   */
   constructor({ agent, logger, packageName, channelName, callback }) {
     super({ agent, logger, packageName, channelName })
     this.callback = callback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newrelic",
-  "version": "13.6.0",
+  "version": "13.6.2",
   "author": "New Relic Node.js agent team <nodejs@newrelic.com>",
   "license": "Apache-2.0",
   "contributors": [