newrelic 14.1.2 → 14.2.0

package/lib/profiling/profilers/cpu.js

@@ -5,15 +5,68 @@
 
 'use strict'
 const BaseProfiler = require('./base')
+const semver = require('semver')
 
+/**
+ * (CPED) Key under which each segment caches its sample context, so the same
+ * span always maps to the same object identity.
+ */
+const PROFILING_CONTEXT = Symbol('NewRelicProfilingContext')
+
+/**
+ * (non-CPED) Empty holder for when no span is active. Frozen so it can't be
+ * mutated in place — pprof reads holders by reference, so we swap in a fresh one
+ * per sample.
+ */
+const DEFAULT_CONTEXT = Object.freeze({ current: {} })
+
+/**
+ * Produces a wall time stack profile via `pprof`.
+ * The native sampler fires at a fixed rate against whatever JS is currently on
+ * the stack, and each sample is tagged with the active transaction's trace/span
+ * ids. We capture those ids by hooking the agent's `AsyncLocalStorage`; pprof
+ * then carries them per sample via CPED when `AsyncContextFrame` is active, or
+ * in a holder we swap per sample otherwise.
+ *
+ * The wall-clock (or just wall) time for a function measures the time elapsed
+ * between entering and exiting a function. Wall time includes all wait time,
+ * including that for locks and thread synchronization.
+ */
 class CpuProfiler extends BaseProfiler {
   #pprof
+  #tracer
   #durationMillis
   #intervalMicros = (1e3 / 99) * 1000 // samples at 99hz(99 times per second)
-  constructor({ logger, samplingInterval }) {
+  #kSampleCount
+  #useCPED
+  /**
+   * (non-CPED) `pprof` captures this holder by reference at sample time, so
+   * we keep `current` pointed at the active transaction's trace/span ids.
+   */
+  #context = DEFAULT_CONTEXT
+  #state
+  #lastSampleCount = 0
+  /**
+   * The agent's `AsyncLocalStorage` instance.
+   */
+  #store
+  // Saved ALS methods, restored by `#unhookContext` on stop.
+  #origRun
+  #origEnterWith
+  /**
+   * (non-CPED) Async hook that refreshes context on async resumption.
+   */
+  #asyncHook
+
+  constructor({ logger, samplingInterval, tracer }) {
     super({ logger })
     this.#pprof = require('@datadog/pprof')
+    this.#kSampleCount = this.#pprof.time.constants.kSampleCount
+    this.#tracer = tracer
+    this.#store = tracer._contextManager._asyncLocalStorage
     this.#durationMillis = samplingInterval
+    // CPED requires AsyncContextFrame which is on by default with node >=24
+    this.#useCPED = semver.satisfies(process.versions.node, '>=24.0.0')
   }
 
   start() {
@@ -25,8 +78,21 @@ class CpuProfiler extends BaseProfiler {
     this.logger.trace(`Starting CpuProfiler, sample every ${this.#intervalMicros}hz for ${this.#durationMillis} ms.`)
     this.#pprof.time.start({
       durationMillis: this.#durationMillis,
-      intervalMicros: this.#intervalMicros
+      intervalMicros: this.#intervalMicros,
+      // needed for trace_id + span_id label
+      withContexts: true,
+      // carry the sample context per async-context-frame when ACF is active
+      useCPED: this.#useCPED
     })
+
+    if (this.#useCPED) {
+      this.#hookEnterWith()
+    } else {
+      this.#state = this.#pprof.time.getState()
+      this.#resetContext()
+      this.#hookRun()
+      this.#hookAsyncResume()
+    }
   }
 
   stop() {
@@ -35,13 +101,169 @@ class CpuProfiler extends BaseProfiler {
       return
     }
 
+    // Restore the wrapped ALS methods before stopping.
+    this.#unhookContext()
     this.#pprof.time.stop(false)
   }
 
   async collect() {
-    const profile = this.#pprof.time.stop(true)
+    if (!this.#useCPED) {
+      // Flush the active span before sampling restarts.
+      this.#updateContext()
+    }
+    const profile = this.#pprof.time.stop(true, this.#generateLabels)
+    if (!this.#useCPED) {
+      // `stop(true)` restarts sampling, so start a fresh holder.
+      this.#resetContext()
+    }
     return this.#pprof.encode(profile)
   }
+
+  /**
+   * Callback that returns the `span_id` and `trace_id`
+   * labels active when each sample was taken.
+   *
+   * @param {object} params params from pprof
+   * @param {object} params.context the captured time profile node context
+   * @returns {object} label set applied to the pprof sample
+   */
+  #generateLabels = ({ context }) => {
+    const capturedContext = context?.context
+    // With CPED the captured value is the label itself; without it,
+    // the label lives in the holder's `current`.
+    const { traceId, spanId } = (this.#useCPED ? capturedContext : capturedContext?.current) ?? {}
+    // A span id only exists when a trace id does, so trace_id anchors the label set:
+    // no trace id means no active span, and span_id is added only when present.
+    if (!traceId) {
+      return {}
+    }
+    return spanId ? { span_id: spanId, trace_id: traceId } : { trace_id: traceId }
+  }
+
+  /**
+   * Refreshes the pprof sample context with the active span. With CPED, the label
+   * is written straight into the current async-context-frame; otherwise a fresh
+   * holder is swapped in once a sample has landed (so earlier samples keep their
+   * ids) before reassigning its `current`.
+   */
+  #updateContext = () => {
+    if (this.#useCPED) {
+      this.#updateCpedContext()
+      return
+    }
+
+    const { 'trace.id': traceId, 'span.id': spanId } = this.#tracer.agent.getLinkingMetadata(true)
+    const spanContext = { traceId, spanId }
+    const sampleCount = this.#state?.[this.#kSampleCount]
+    if (sampleCount !== this.#lastSampleCount || this.#context === DEFAULT_CONTEXT) {
+      this.#lastSampleCount = sampleCount
+      this.#context = { current: spanContext }
+      this.#pprof.time.setContext(this.#context)
+    } else {
+      this.#context.current = spanContext
+    }
+  }
+
+  /**
+   * (CPED) Installs the active span's context into the current async-context-frame.
+   * Each segment's `{ traceId, spanId }` is built once and cached on the segment
+   * (its ids never change), and `setContext` is only called when the frame isn't
+   * already holding that object, skipping the redundant native write pprof would
+   * otherwise do every time a frame is entered or restored.
+   */
+  #updateCpedContext() {
+    const segment = this.#tracer.getSegment()
+    let spanContext = Object.freeze({})
+    if (segment) {
+      spanContext = segment[PROFILING_CONTEXT]
+      if (spanContext === undefined) {
+        const { 'trace.id': traceId, 'span.id': spanId } = this.#tracer.agent.getLinkingMetadata(true)
+        spanContext = segment[PROFILING_CONTEXT] = { traceId, spanId }
+      }
+    }
+
+    if (this.#pprof.time.getContext() !== spanContext) {
+      this.#pprof.time.setContext(spanContext)
+    }
+  }
+
+  /**
+   * (non-CPED) Points the pprof time profiler at a fresh `#context`
+   * and resyncs the sample counter.
+   */
+  #resetContext() {
+    this.#context = DEFAULT_CONTEXT
+    this.#lastSampleCount = this.#state?.[this.#kSampleCount] ?? 0
+    this.#pprof.time.setContext(this.#context)
+  }
+
+  /**
+   * (CPED) Wraps `enterWith` on the agent's `AsyncLocalStorage`. Since `run`
+   * delegates to `enterWith` under ACF, this one hook covers every context
+   * switch; we then `setContext` the active span into the current frame, which
+   * pprof propagates to continuations and restores on unwind.
+   */
+  #hookEnterWith() {
+    const self = this
+    this.#origEnterWith = this.#store.enterWith
+    const origEnterWith = this.#origEnterWith
+    this.#store.enterWith = function (store) {
+      const retVal = origEnterWith.call(this, store)
+      self.#updateContext()
+      return retVal
+    }
+  }
+
+  /**
+   * (non-CPED) Wraps `run` on the agent's `AsyncLocalStorage` to refresh the
+   * holder on `run` entry and exit (so a sibling doesn't inherit a returned
+   * child's span). Wraps the instance, not the prototype.
+   */
+  #hookRun() {
+    const self = this
+    this.#origRun = this.#store.run
+    const origRun = this.#origRun
+    this.#store.run = function (store, callback, ...args) {
+      function wrapped(...cbArgs) {
+        self.#updateContext()
+        return callback.apply(this, cbArgs)
+      }
+      try {
+        return origRun.call(this, store, wrapped, ...args)
+      } finally {
+        self.#updateContext()
+      }
+    }
+  }
+
+  /**
+   * (non-CPED) Async resumptions (timer, promise, I/O) restore the active store
+   * without a `run` call, leaving the holder frozen at the last `run`'s span. A
+   * `before` hook refreshes it so those samples get the right span.
+   */
+  #hookAsyncResume() {
+    // eslint-disable-next-line n/no-unsupported-features/node-builtins
+    const { createHook } = require('async_hooks')
+    this.#asyncHook = createHook({ before: () => this.#updateContext() })
+    this.#asyncHook.enable()
+  }
+
+  /**
+   * Restores the original `run`/`enterWith` and disables the async hook so none
+   * fire once the profiler has stopped.
+   */
+  #unhookContext() {
+    if (this.#origRun) {
+      this.#store.run = this.#origRun
+      this.#origRun = null
+    }
+    if (this.#origEnterWith) {
+      this.#store.enterWith = this.#origEnterWith
+      this.#origEnterWith = null
+    }
+    this.#asyncHook?.disable()
+    this.#asyncHook = null
+  }
 }
 
 module.exports = CpuProfiler

package/lib/subscriber-configs.js

@@ -32,6 +32,7 @@ const subscribers = {
   ...require('./subscribers/langgraph/config'),
   ...require('./subscribers/mcp-sdk/config'),
   ...require('./subscribers/memcached/config'),
+  ...require('./subscribers/mongodb/config'),
   ...require('./subscribers/mysql/config'),
   ...require('./subscribers/mysql2/config'),
   ...require('./subscribers/nestjs/config'),

package/lib/subscribers/base.js

@@ -188,11 +188,12 @@ class Subscriber {
    * @param {object} [params.recorder] - Optional recorder for the segment
    * @param {Context} params.ctx - The context containing the parent segment and
    * transaction
+   * @param {object} [params.attributes] See {@link #addAttributes}.
    *
    * @returns {AsyncContext} - The updated context with the new segment or
    * existing context if segment creation fails
    */
-  createSegment({ name, recorder, ctx }) {
+  createSegment({ name, recorder, ctx, attributes = null }) {
     const parent = ctx?.segment
 
     if (this.shouldCreateSegment(parent) === false) {
@@ -212,7 +213,7 @@ class Subscriber {
       segment.shimId = this.packageName
       segment.start()
       this.logger.trace('Created segment %s, returning new context', name)
-      this.addAttributes(segment)
+      this.addAttributes(segment, attributes)
       return ctx.enterSegment({ segment })
     } else {
       this.logger.trace('Failed to create segment for %s, returning existing context', name)
@@ -221,13 +222,19 @@ class Subscriber {
   }
 
   /**
-   * By default this is a no-op, but can be overridden by subclasses
-   * @param {Segment} segment - The segment to which attributes will be added
+   * By default, this is a no-op, but can be overridden by subclasses.
+   *
+   * @param {Segment} segment The segment to which attributes will be added
+   * @param {object} [attributes] A set of attributes to add to the
+   * segment. Some subclasses, e.g. the {@link DbSubscriber} subclass, have
+   * a mechanism to supply these as an object property
+   * (`subscriber.parameters`). But there are cases where the attributes must
+   * be calculated during the transaction, and are thus easier to pass through
+   * via this parameter.
+   *
    * @returns {void}
    */
-  addAttributes(segment) {
-
-  }
+  addAttributes(segment, attributes) {}
 
   /**
    * Not all subscribers need to change the context on an event.

package/lib/subscribers/db.js

@@ -14,6 +14,8 @@ const urltils = require('../util/urltils')
  * - `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
  */
 class DbSubscriber extends Subscriber {
   /**
@@ -50,9 +52,16 @@ class DbSubscriber extends Subscriber {
   /**
    * Adds `this.parameters` to the active segment.
    * @param {object} segment the current segment
+   * @param {object} [attributes] Attributes to add. Defaults to
+   * `this.parameters`. If both are defined, this value takes precedence.
    */
-  addAttributes(segment) {
-    for (let [key, value] of Object.entries(this.parameters ?? {})) {
+  addAttributes(segment, attributes = {}) {
+    const parameters = Object.assign(
+      {},
+      this.parameters ?? {},
+      attributes
+    )
+    for (let [key, value] of Object.entries(parameters)) {
       if (this.instanceKeys.includes(key) && !this.instanceReporting) {
         continue
       }

package/lib/subscribers/mongodb/bulk.js

@@ -0,0 +1,79 @@
+/*
+ * 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')
+
+/**
+ * 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 CURSOR_METHODS = [
+  'execute'
+]
+
+module.exports = class BulkSubscriber extends Wrapper {
+  constructor({ agent, logger }) {
+    super({
+      agent,
+      logger,
+      channelName: 'nr_bulk',
+      packageName: 'mongodb',
+      system: MONGODB_METRIC_CONSTANTS.PREFIX
+    })
+  }
+
+  end(data, ctx) {
+    const { self: bulkOperation, arguments: args } = data
+    const [collection] = args
+    const collectionName = collection.collectionName
+    const details = getHostDetails(collection)
+    this.parameters = {
+      host: details.host,
+      port_path_or_id: details.port_path_or_id,
+      database_name: details.database_name,
+      product: this.system
+    }
+
+    for (const method of CURSOR_METHODS) {
+      if (typeof bulkOperation[method] !== 'function') {
+        continue
+      }
+
+      this.wrapDatabaseMethod(bulkOperation, method, {
+        getSegmentName: () => {
+          const operation = bulkOperation.isOrdered ? 'orderedBulk' : 'unorderedBulk'
+          return `${DB_METRIC_CONSTANTS.STATEMENT}/${this.system}/${collectionName}/${operation}/batch`
+        },
+        getRecorderContext: () => {
+          return {
+            operation: bulkOperation.isOrdered ? 'orderedBulk' : 'unorderedBulk',
+            collection: collectionName,
+            type: this.type
+          }
+        },
+        getSegmentAttributes: (method) => (
+          ADMIN_COMMANDS.includes(method)
+            ? { database_name: 'admin' }
+            : {}
+        )
+      })
+    }
+
+    return ctx
+  }
+}

package/lib/subscribers/mongodb/collection.js

@@ -0,0 +1,113 @@
+/*
+ * 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')
+
+/**
+ * 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 CURSOR_METHODS = [
+  'aggregate',
+  'bulkWrite',
+  'count',
+  'createIndex',
+  'deleteMany',
+  'deleteOne',
+  'distinct',
+  'drop',
+  'dropAllIndexes',
+  'dropIndex',
+  'ensureIndex',
+  'findAndModify',
+  'findAndRemove',
+  'findOne',
+  'findOneAndDelete',
+  'findOneAndReplace',
+  'findOneAndUpdate',
+  'geoHaystackSearch',
+  'geoNear',
+  'group',
+  'indexExists',
+  'indexInformation',
+  'indexes',
+  'insert',
+  'insertMany',
+  'insertOne',
+  'isCapped',
+  'mapReduce',
+  'options',
+  'parallelCollectionScan',
+  'reIndex',
+  'remove',
+  'rename',
+  'replaceOne',
+  'save',
+  'stats',
+  'update',
+  'updateMany',
+  'updateOne'
+]
+
+module.exports = class CollectionSubscriber extends Wrapper {
+  constructor({ agent, logger }) {
+    super({
+      agent,
+      logger,
+      channelName: 'nr_collection',
+      packageName: 'mongodb',
+      system: MONGODB_METRIC_CONSTANTS.PREFIX
+    })
+  }
+
+  end(data, ctx) {
+    const { self: dbClient, arguments: args } = data
+    const [dbInstance, collectionName] = args
+    const details = getHostDetails(dbInstance)
+    this.parameters = {
+      host: details.host,
+      port_path_or_id: details.port_path_or_id,
+      database_name: details.database_name,
+      product: this.system
+    }
+
+    for (const method of CURSOR_METHODS) {
+      if (typeof dbClient[method] !== 'function') {
+        continue
+      }
+
+      this.wrapDatabaseMethod(dbClient, method, {
+        getSegmentName: (method) => `${DB_METRIC_CONSTANTS.STATEMENT}/${this.system}/${collectionName}/${method}`,
+        getRecorderContext: (method) => {
+          return {
+            operation: method,
+            collection: collectionName,
+            type: this.type
+          }
+        },
+        getSegmentAttributes: (method) => (
+          ADMIN_COMMANDS.includes(method)
+            ? { database_name: 'admin' }
+            : {}
+        )
+      })
+    }
+
+    return ctx
+  }
+}

package/lib/subscribers/mongodb/config.js

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2026 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const modName = 'mongodb'
+
+module.exports = {
+  [modName]: [
+    {
+      path: './mongodb/db.js',
+      instrumentations: [{
+        module: {
+          name: modName,
+          filePath: 'lib/db.js',
+          versionRange: '>=4.1.4'
+        },
+        channelName: 'nr_db',
+        functionQuery: {
+          className: 'Db'
+        }
+      }]
+    },
+
+    {
+      path: './mongodb/cursor.js',
+      instrumentations: [{
+        module: {
+          name: modName,
+          filePath: 'lib/cursor/abstract_cursor.js',
+          versionRange: '>=4.1.4'
+        },
+        channelName: 'nr_cursor',
+        functionQuery: {
+          className: 'AbstractCursor'
+        }
+      }]
+    },
+
+    {
+      path: './mongodb/collection.js',
+      instrumentations: [{
+        module: {
+          name: modName,
+          filePath: 'lib/collection.js',
+          versionRange: '>=4.1.4'
+        },
+        channelName: 'nr_collection',
+        functionQuery: {
+          className: 'Collection'
+        }
+      }]
+    },
+
+    {
+      path: './mongodb/bulk.js',
+      instrumentations: [{
+        module: {
+          name: modName,
+          filePath: 'lib/bulk/common.js',
+          versionRange: '>=4.1.4'
+        },
+        channelName: 'nr_bulk',
+        functionQuery: {
+          className: 'BulkOperationBase'
+        }
+      }]
+    }
+  ]
+}

package/lib/subscribers/mongodb/cursor.js

@@ -0,0 +1,76 @@
+/*
+ * 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')
+
+/**
+ * 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 CURSOR_METHODS = [
+  'count',
+  'explain',
+  // `forEach` is for mongodb@4 through mongodb@7. It is slated to be
+  // removed in some version after 7.
+  'forEach',
+  'next',
+  'nextObject',
+  'toArray'
+]
+
+module.exports = class CursorSubscriber extends Wrapper {
+  constructor({ agent, logger }) {
+    super({
+      agent,
+      logger,
+      channelName: 'nr_cursor',
+      packageName: 'mongodb',
+      system: MONGODB_METRIC_CONSTANTS.PREFIX
+    })
+  }
+
+  end(data, ctx) {
+    const { self: dbClient, arguments: args } = data
+    const [mongoClient, dbNamespace] = args
+    const { collection } = dbNamespace
+    const details = getHostDetails(mongoClient)
+    this.parameters = {
+      host: details.host,
+      port_path_or_id: details.port_path_or_id,
+      database_name: dbNamespace.db,
+      product: this.system
+    }
+
+    for (const method of CURSOR_METHODS) {
+      if (typeof dbClient[method] !== 'function') {
+        continue
+      }
+
+      this.wrapDatabaseMethod(dbClient, method, {
+        getSegmentName: (method) => `${DB_METRIC_CONSTANTS.STATEMENT}/${this.system}/${collection}/${method}`,
+        getRecorderContext: (method) => {
+          return {
+            operation: method,
+            collection,
+            type: this.type
+          }
+        }
+      })
+    }
+
+    return ctx
+  }
+}