newrelic 14.1.2 → 14.2.1

package/lib/subscribers/mongodb/db.js

@@ -0,0 +1,101 @@
+/*
+ * Copyright 2026 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const Wrapper = require('./wrapper.js')
+const getHostDetails = require('./utils/get-host-details.js')
+
+const {
+  DB: DB_METRIC_CONSTANTS,
+  MONGODB: MONGODB_METRIC_CONSTANTS
+} = require('#agentlib/metrics/names.js')
+
+const ADMIN_COMMANDS = require('./utils/admin-commands.js')
+
+/**
+ * The "Db" class is the primary entrypoint into the mongodb client. Some
+ * methods are not present on newer versions of the class, e.g. `addUser`
+ * got removed in favor of a direct `command` invocation. This list is a list
+ * of all methods we are interested in instrumenting, regardless of client
+ * version. As we iterate through the list we will perform a presence check
+ * for each method.
+ *
+ * @type {string[]}
+ */
+const DB_METHODS = [
+  '_executeInsertCommand',
+  '_executeQueryCommand',
+  'addUser',
+  'authenticate',
+  'collection',
+  'collectionNames',
+  'collections',
+  'command',
+  'createCollection',
+  'createIndex',
+  'cursorInfo',
+  'dereference',
+  'dropCollection',
+  'dropDatabase',
+  'dropIndex',
+  'ensureIndex',
+  'eval',
+  'executeDbAdminCommand',
+  'indexInformation',
+  'logout',
+  'open',
+  'reIndex',
+  'removeUser',
+  'renameCollection',
+  'stats'
+]
+
+module.exports = class DbClassSubscriber extends Wrapper {
+  constructor({ agent, logger }) {
+    super({
+      agent,
+      logger,
+      channelName: 'nr_db',
+      packageName: 'mongodb',
+      system: MONGODB_METRIC_CONSTANTS.PREFIX
+    })
+  }
+
+  end(data, ctx) {
+    const { self: dbClient, arguments: args } = data
+    const [dbInstance, dbName] = args
+    const details = getHostDetails(dbInstance)
+    this.parameters = {
+      host: details.host,
+      port_path_or_id: details.port_path_or_id,
+      database_name: dbName,
+      product: this.system
+    }
+
+    for (const method of DB_METHODS) {
+      if (typeof dbClient[method] !== 'function') {
+        continue
+      }
+
+      this.wrapDatabaseMethod(dbClient, method, {
+        getSegmentName: (method) => `${DB_METRIC_CONSTANTS.OPERATION}/${this.system}/${method}`,
+        getRecorderContext: (method) => {
+          return {
+            operation: method,
+            type: this.type
+          }
+        },
+        getSegmentAttributes: (method) => (
+          ADMIN_COMMANDS.includes(method)
+            ? { database_name: 'admin' }
+            : {}
+        )
+      })
+    }
+
+    return ctx
+  }
+}

package/lib/subscribers/mongodb/utils/admin-commands.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2026 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+/**
+ * Represents the list of methods/commmands that are available in the MongoDB
+ * client which target the "admin" collection instead of the actually selected
+ * collection.
+ *
+ * @see https://jira.mongodb.org/browse/NODE-827
+ * @type {string[]}
+ */
+module.exports = [
+  'rename',
+  'renameCollection'
+]

package/lib/subscribers/mongodb/utils/get-host-details.js

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2026 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const LOCALHOST_ALIASES = [
+  '127.0.0.1',
+  '::1',
+  '[::1]'
+]
+
+/**
+ * @typedef {object} MongodbHostDetails
+ * @property {string} [database_name] The name of the database.
+ * @property {string} host The first host being targeted by the connection.
+ * @property {string|number} port_path_or_id The destination port associated
+ * with `host`.
+ */
+
+/**
+ * Retrieves the connection details (host, port, collection_name) from the
+ * provided MongoDB object instance. Over versions of the driver, the location
+ * of these details get moved around. So we need to inspect various locations
+ * for availability and use the first one we can find.
+ *
+ * Important: in the case where the `mongoObject` is a direct instance of
+ * `MongoClient`, or other object that does not include database name details,
+ * the `database_name` field will be omitted. You must acquire this through
+ * other means.
+ *
+ * @param {object} mongoObject The MongoDB driver object to get the details
+ * from, e.g. an 'AbstractCursor' or 'BulkOperationBase' instance.
+ *
+ * @returns {MongodbHostDetails}
+ */
+module.exports = function getHostDetails(mongoObject) {
+  // We prefer to get the details from the "client" object. This is the object
+  // the driver returns when you do `require('mongodb').MongoClient.connect()`.
+
+  let databaseName
+  let host
+  let port
+
+  if (mongoObject.constructor.name === 'MongoClient') {
+    host = mongoObject.options.hosts[0].host
+    port = mongoObject.options.hosts[0].port
+  } else if (mongoObject?.databaseName && mongoObject?.client) {
+    // Direct `Db` instance.
+    databaseName = mongoObject.databaseName
+    host = mongoObject.client.options.hosts[0].host
+    port = mongoObject.client.options.hosts[0].port
+  } else if (mongoObject.dbName && mongoObject.s?.db?.s?.client?.options) {
+    // Likely an instance of `Collection`.
+    databaseName = mongoObject.dbName
+    host = mongoObject.s.db.s.client.options.hosts[0].host
+    port = mongoObject.s.db.s.client.options.hosts[0].port
+  } else if (mongoObject.databaseName && mongoObject.s?.client?.options) {
+    // Some `mongodb@4` object.
+    databaseName = mongoObject.databaseName
+    host = mongoObject.s.client.options.hosts[0].host
+    port = mongoObject.s.client.options.hosts[0].port
+  } else if (mongoObject?.s?.db && mongoObject.s.db.client) {
+    // mongodb@5 bulk operation
+    databaseName = mongoObject.s.db.databaseName
+    host = mongoObject.s.db.client.options.hosts[0].host
+    port = mongoObject.s.db.client.options.hosts[0].port
+  } else if (mongoObject.constructor.name === 'Topology') {
+    // A "topology" object (from ancient times). Remove this when we drop
+    // support for v4.
+    host = mongoObject.s.options.hosts[0].host
+    port = mongoObject.s.options.hosts[0].port
+  }
+
+  if (LOCALHOST_ALIASES.includes(host) === true) {
+    host = 'localhost'
+  }
+
+  return {
+    database_name: databaseName,
+    port_path_or_id: port,
+    host
+  }
+}

package/lib/subscribers/mongodb/wrapper.js

@@ -0,0 +1,109 @@
+/*
+ * Copyright 2026 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const DbSubscriber = require('../db.js')
+const databaseRecorder = require('#agentlib/metrics/recorders/database.js')
+
+/**
+ * This class provides a baseline for the MongoDB instrumentations that
+ * share a lot of common code when wrapping methods, but require some slight
+ * variations in the collected data. Anything extending this class is
+ * expected to leverage the {@link #wrapDatabaseMethod} method.
+ */
+module.exports = class WrapperSubscriber extends DbSubscriber {
+  constructor(params) {
+    super(params)
+
+    this.events = ['end']
+    // We set `opaque` to true because the library uses its own methods
+    // internally, and we only care about the entry point. That is, if the
+    // code is `.findOne('something')`, the  method will invoke `.next`
+    // internally. We don't care to track `.next` with its own reported segment.
+    // We only want to record the overall operation of `.findOne`.
+    //
+    // This is the case for all instrumentations that inherit from this class.
+    // The details change around the methods, but the desired outcome
+    // is the same.
+    this.opaque = true
+
+    // The database metrics recorder reads `this.type` to get the name of the
+    // database system.
+    this.type = this.system
+  }
+
+  /**
+   * Creates a standard database operation wrapper for a method.
+   * This method provides a common pattern for instrumenting database operations
+   * with transaction validation, segment creation, and database recording.
+   *
+   * @param {object} instance The instance with the method to wrap.
+   * @param {string} methodName The name of the method to wrap.
+   * @param {object} callbacks Functions used to retrieve context specific
+   * data.
+   * @param {Function} callbacks.getSegmentName Each subscriber names its
+   * segment slightly differently. This function should return the full
+   * string representation for the segment name.
+   * @param {Function} callbacks.getRecorderContext Each subscriber instruments
+   * multiple methods that can be invoked during the evaluation of one
+   * operation. As such, the instances cannot store details relevant to metrics
+   * generation on the instance itself. Thus, we need a scoped context object
+   * to provide to the metrics recorder function. This function is used to
+   * get a copy of that scoped context object.
+   * @param {Function} [callbacks.getSegmentAttributes] In most cases, the
+   * `addAttributes` method on the base class can be used to get a copy of
+   * attributes to add to the segment being recorded. But there are some cases
+   * where the attributes need to be calculated within the scope of the
+   * transaction and passed in to the `addAttributes` method. This function
+   * is used to get a copy of the attributes object to provide to the
+   * base method.
+   */
+  wrapDatabaseMethod(instance, methodName, callbacks) {
+    const self = this
+    const orig = instance[methodName]
+    const {
+      getSegmentName,
+      getRecorderContext,
+      getSegmentAttributes = () => { return {} }
+    } = callbacks
+
+    instance[methodName] = function nrWrappedMethod(...args) {
+      let ctx = self.agent.tracer.getContext()
+      if (ctx.transaction == null || ctx.transaction.isActive() === false) {
+        self.logger.debug(
+          'Not recording function %s, not in a transaction',
+          methodName
+        )
+        return orig.apply(instance, args)
+      }
+
+      self.logger.debug('Recording function %s', methodName)
+
+      ctx = self.createSegment({
+        name: getSegmentName(methodName),
+        recorder: function dbRecorder(segment, scope, transaction) {
+          const recorderContext = getRecorderContext(methodName)
+          return databaseRecorder.call(
+            recorderContext,
+            segment,
+            scope,
+            transaction
+          )
+        },
+        attributes: getSegmentAttributes(methodName),
+        ctx
+      })
+
+      return self.agent.tracer.runInContext({
+        handler: orig,
+        context: ctx,
+        full: true,
+        thisArg: instance,
+        args
+      })
+    }
+  }
+}

package/lib/subscribers/resolve-package-version.js

@@ -15,6 +15,22 @@ const modPathReg = /at .+ \((.+):\d+:\d+\)/
 
 module.exports = resolveModuleVersion
 
+/**
+ * Captures the current call stack, dropping frames up to and including the
+ * `Channel.publish` frame so that the first returned frame belongs to the
+ * module that published the diagnostics channel event.
+ *
+ * @returns {string[]} The remaining stack frames.
+ */
+function defaultGetStack() {
+  const err = Error()
+  const stack = err.stack.split('\n')
+  do {
+    stack.shift()
+  } while (dcFuncFrame.test(stack[0]) === false && stack.length > 0)
+  return stack
+}
+
 /**
  * Given a module name, attempt to read the version string from its
  * associated package manifest. If the module is a built-in, or one that has
@@ -32,30 +48,44 @@ module.exports = resolveModuleVersion
  * @param {string} moduleSpecifier What would be passed to `resolve()`.
  * @param {object} [deps] Optional dependencies.
  * @param {object} [deps.logger] Agent logger instance.
+ * @param {Function} [deps.getStack] Returns the current call stack as an array
+ * of frame strings. Exposed for testing so a synthetic publisher frame can be
+ * supplied.
  *
  * @returns {string} The version string from the package manifest or "unknown".
  */
-function resolveModuleVersion(moduleSpecifier, { logger = defaultLogger } = {}) {
+function resolveModuleVersion(
+  moduleSpecifier,
+  { logger = defaultLogger, getStack = defaultGetStack } = {}
+) {
   let pkgPath
   // We'd prefer to use `require.resolve(moduleSpecifier)` here, but it gets
   // a bit confused when there are non-standard module directories in play.
   // Once we are able to refactor our "on require" metric recording to
   // utilize `module.registerHooks`, we should be able to eliminate this
   // slow algorithm.
-  const err = Error()
-  const stack = err.stack.split('\n')
-  do {
-    stack.shift()
-  } while (dcFuncFrame.test(stack[0]) === false && stack.length > 0)
+  const stack = getStack()
   const matches = modPathReg.exec(stack[1])
   pkgPath = matches?.[1]
 
-  if (!pkgPath) {
-    logger.warn(
-      { moduleSpecifier },
-      'Could not resolve module path. Possibly a built-in or Node.js bundled module.'
-    )
-    return 'unknown'
+  // When the diagnostics channel event is published by a Node.js built-in or
+  // bundled module (e.g. `node:internal/deps/undici/undici`), `pkgPath` is not
+  // a real filesystem path, so the directory walk below cannot use it. This
+  // happens on modern Node.js versions where userland `undici` reuses Node's
+  // internally bundled undici channels. In that case, resolve the userland
+  // package manifest directly to report the version the application installed.
+  if (!pkgPath || pkgPath.startsWith('node:')) {
+    try {
+      const { version } = require(`${moduleSpecifier}/package.json`)
+      logger.trace({ moduleSpecifier, version }, 'Resolved package version.')
+      return version ?? 'unknown'
+    } catch {
+      logger.warn(
+        { moduleSpecifier },
+        'Could not resolve module path. Possibly a built-in or Node.js bundled module.'
+      )
+      return 'unknown'
+    }
   }
 
   const cwd = process.cwd()

package/lib/subscribers/winston/configure.js

@@ -12,11 +12,18 @@ const NrTransport = require('./nr-winston-transport.js')
  * during initial construction and on any subsequent reconfiguration.
  *
  * Handles `NrTransport` injection (after `configure` runs, via `end`).
+ *
+ * @property {boolean} handlingExceptions Indicates if this instrumentation has
+ * already registered a global exception handler or not. We only need a single
+ * exception handler per process.
  */
 module.exports = class WinstonConfigure extends ApplicationLogsSubscriber {
   constructor({ agent, logger }) {
     super({ agent, logger, channelName: 'nr_configure', packageName: 'winston' })
     this.events = ['end']
+    // we only want to assign `handleExceptions` to the first NrTransport
+    // customers could be constructing multiple logger instances
+    this.handlingExceptions = false
   }
 
   handler(data, ctx) {
@@ -39,11 +46,12 @@ module.exports = class WinstonConfigure extends ApplicationLogsSubscriber {
     const hasNrTransport = logger.transports?.some((t) => t.name === 'newrelic')
     if (!hasNrTransport) {
       const nrTransport = new NrTransport({ agent: this.agent })
-      // Only handle exceptions if the logger has user-configured transports.
-      // This prevents the default logger (created during require('winston')
-      // module init with no transports) from double-handling exceptions.
-      if (logger.transports.length === 0) {
-        nrTransport.handleExceptions = false
+      // assigning `transport.handleExceptions` adds a global `process.on('uncaughtException')`
+      // handler. Doing it for more than one NrTransport instance will cause duplicate log lines
+      if (this.handlingExceptions === false && logger.transports.length > 0) {
+        // See: https://github.com/winstonjs/winston#handling-uncaught-exceptions-with-winston
+        nrTransport.handleExceptions = true
+        this.handlingExceptions = true
       }
       logger.add(nrTransport)
     }

package/lib/subscribers/winston/nr-winston-transport.js

@@ -14,12 +14,15 @@ const { truncate } = require('../../util/application-logging')
  *
  * Note*: This copies the log line so no other transports will get the
  * mutated data.
+ *
+ * @property {string} name name of the transport
+ * @property {Agent} agent the instance of agent
+ * @property {object} config the agent configuration
+ * @property {boolean} handleExceptions set in `lib/subscribers/winston/configure.js` for the first NrTransport instance
+ * to ensure that only one is handling uncaught exceptions in winston transports
  */
 class NrTransport extends TransportStream {
   constructor(opts = {}) {
-    // set this option to have winston handle uncaught exceptions
-    // See: https://github.com/winstonjs/winston#handling-uncaught-exceptions-with-winston
-    opts.handleExceptions = true
     super(opts)
     this.name = 'newrelic'
     this.agent = opts.agent

package/lib/transaction/tracecontext.js

@@ -72,10 +72,9 @@ class TraceContext {
   /**
    * Creates a W3C TraceContext tracestate header payload.
    *
-   * @param {object} spanContext if passed in, it'll use this to construct tracestate. only used in otel bridge mode.
    * @returns {string} tracestate, a hyphen-delimited string of trace information fields
    */
-  createTracestate(spanContext) {
+  createTracestate() {
     const config = this.transaction.agent.config
     const trustedAccountKey = config.trusted_account_key
     const version = Tracestate.NR_TRACESTATE_VERSION
@@ -99,29 +98,17 @@ class TraceContext {
       return this._traceStateRaw || ''
     }
 
-    // If no segment/span is in context, we do not send one as
-    // we technically do not have a "span" on the agent side and
-    // this trace data is newrelic specific.
-    let spanId = ''
-    if (config.span_events.enabled) {
-      const segment = spanContext?.spanId ? { id: spanContext.spanId } : this.transaction.agent.tracer.getSegment()
-      if (segment) {
-        spanId = segment.id
-      } else {
-        logger.debug('No segment/span in context. Not sending spanId in tracestate.')
-      }
-    } else {
-      logger.trace('Span events disabled. Not sending spanId in tracestate.')
-    }
-
     const transactionId = config.transaction_events.enabled ? this.transaction.id : ''
     const sampled = this.transaction.sampled ? '1' : '0'
     const priority = this.transaction.priority ? this.transaction.priority.toFixed(6) : ''
     const timestamp = Date.now()
 
+    // As of 2026-06 we no longer emit spanId under any circumstance.
+    // So we omit it from the list here as this is the source
+    // when building the outgoing tracestate header.
     const nrTraceState =
       `${trustedAccountKey}@nr=${version}-${parentType}-${accountId}` +
-      `-${appId}-${spanId}-${transactionId}-${sampled}-${priority}-${timestamp}`
+      `-${appId}--${transactionId}-${sampled}-${priority}-${timestamp}`
 
     if (this._traceStateRaw) {
       return `${nrTraceState},${this._traceStateRaw}`
@@ -151,7 +138,7 @@ class TraceContext {
 
     logger.trace('traceparent added with %s', traceParent)
 
-    const tracestate = this.createTracestate(spanContext)
+    const tracestate = this.createTracestate()
     if (tracestate) {
       if (setter) {
         setter.set(headers, TRACE_CONTEXT_STATE_HEADER, tracestate)

package/lib/transaction/tracer/index.js

@@ -306,6 +306,22 @@ function _maybeBindPromise({ result, full, segment }) {
   }
 }
 
+/**
+ * Invokes a function within the scope of the given context. If the original
+ * function returns a promise, that promise will be bound to the correct
+ * segment.
+ *
+ * @param {object} params Function parameters.
+ * @param {Function} params.handler The original function to invoke.
+ * @param {AsyncContext} params.context The context for the invocation.
+ * @param {boolean} [params.full] When set to `true`, the provided segment
+ * will be started and ended automatically.
+ * @param {object} params.thisArg Entity to use as the `this` binding when
+ * invoking the original function.
+ * @param {*[]} params.args Array of arguments to provide to the function.
+ *
+ * @returns {*} Whatever the instrumented function returns.
+ */
 function runInContext({ handler, context, full, thisArg, args }) {
   const { segment } = context
   if (segment && full) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newrelic",
-  "version": "14.1.2",
+  "version": "14.2.1",
   "author": "New Relic Node.js agent team <nodejs@newrelic.com>",
   "license": "Apache-2.0",
   "contributors": [
@@ -170,7 +170,7 @@
     "lint:fix": "eslint --fix .",
     "public-docs": "jsdoc -c ./jsdoc-conf.jsonc",
     "publish-docs": "./bin/publish-docs.sh",
-    "services": "DOCKER_PLATFORM=linux/$(uname -m) docker compose up -d --wait",
+    "services": "./bin/start-services.sh",
     "services:start": "npm run services",
     "services:stop": "docker compose down",
     "smoke": "time borp --timeout 180000 --reporter ./test/lib/test-reporter.mjs 'test/smoke/**/*.test.js'",
@@ -223,9 +223,9 @@
     "winston-transport": "^4.5.0"
   },
   "optionalDependencies": {
-    "@datadog/pprof": "^5.13.3",
-    "@newrelic/fn-inspect": "^5.0.0",
-    "@newrelic/native-metrics": "^13.0.0",
+    "@datadog/pprof": "^5.14.2",
+    "@newrelic/fn-inspect": "^5.1.0",
+    "@newrelic/native-metrics": "^13.1.0",
     "@prisma/prisma-fmt-wasm": "^4.17.0-16.27eb2449f178cd9fe1a4b892d732cc4795f75085"
   },
   "devDependencies": {