newrelic 11.13.0 → 11.14.0

package/NEWS.md

@@ -1,39 +1,60 @@
-### v11.13.0 (2024-03-13)
-
-#### Features
-
-* Added AI Monitoring(AIM) for OpenAI, Amazon Bedrock, and Langchain.
-  * To enable set `config.ai_monitoring.enabled` or `NEW_RELIC_AI_MONITORING_ENABLED` to `true`.
-  * It is recommended for a full experience to set `config.span_events.max_samples_stored` to `10000`, `config.custom_insights_events.max_samples_stored` to `100000`, and `config.distributed_tracing.enabled` should not be set to false.
-  * **Note**: Enabling [high-security mode](https://docs.newrelic.com/docs/apm/agents/manage-apm-agents/configuration/high-security-mode/) will disable the AIM instrumentation and events. 
-* Added instrumentation for VectorStore.similaritySearch for langchain.js ([#2049](https://github.com/newrelic/node-newrelic/pull/2049)) ([3c50606](https://github.com/newrelic/node-newrelic/commit/3c50606a57a8dc18c91fe36e3b180bafd15a4cbc))
-* Added setLlmTokenCountCallback API endpoint to register a callback for calculating token count when none is provided ([#2065](https://github.com/newrelic/node-newrelic/pull/2065)) ([d2faf1a](https://github.com/newrelic/node-newrelic/commit/d2faf1a4942aacefd8b92e0bc2dc11bd8b687328))
-* Added token_count to LlmEmbedding and LlmChatCompletionMessage for openai ([#2061](https://github.com/newrelic/node-newrelic/pull/2061)) ([47a925e](https://github.com/newrelic/node-newrelic/commit/47a925eccce8e5b5d682b46277bbef5191f8b553))
-* Added tool_id to langchain error event ([#2064](https://github.com/newrelic/node-newrelic/pull/2064)) ([793abe8](https://github.com/newrelic/node-newrelic/commit/793abe8c9854b80fb1cf42f839a7db6a646cdc0b))
-
-#### Miscellaneous chores
-
-* Added flag for verbosity during docs publishing ([#2060](https://github.com/newrelic/node-newrelic/pull/2060)) ([fe0d41a](https://github.com/newrelic/node-newrelic/commit/fe0d41a86cba8da6173f5935e61c62b7dca75344))
-* Added some delays to docs publishing ([#2062](https://github.com/newrelic/node-newrelic/pull/2062)) ([a602fd4](https://github.com/newrelic/node-newrelic/commit/a602fd48e929437e4bc933c4ce276989013c53f1))
-* Changed casing of OpenAI in vendor property ([#2068](https://github.com/newrelic/node-newrelic/pull/2068)) ([64b4ca2](https://github.com/newrelic/node-newrelic/commit/64b4ca2750c9de8d9028fef515c15019e358a5d9))
-* Changed token_count to only use tokenCountCallback ([#2070](https://github.com/newrelic/node-newrelic/pull/2070)) ([66f94b0](https://github.com/newrelic/node-newrelic/commit/66f94b05aa7018af6fa1db1d2d87de9013f23a5b))
-* Removed langchain_instrumentation feature flag as the instrumentation is feature complete ([#2073](https://github.com/newrelic/node-newrelic/pull/2073)) ([925a463](https://github.com/newrelic/node-newrelic/commit/925a463c708b29c78567aecf78ac89ac226b7995))
-* updated @newrelic/aws-sdk and @newrelic/koa to latest ([#2074](https://github.com/newrelic/node-newrelic/pull/2074)) ([0747ca4](https://github.com/newrelic/node-newrelic/commit/0747ca4f0f6615e1fbfcc734a36059960facf23e))
-
-### v11.12.0 (2024-03-04)
-
-#### Features
-
-* Added instrumentation for `chain.stream` for langchain js. ([#2052](https://github.com/newrelic/node-newrelic/pull/2052)) ([03abfce](https://github.com/newrelic/node-newrelic/commit/03abfce666d3c48abd0994c44817bb5cbe8655a9))
-
-#### Miscellaneous chores
-
-* Added @azure/openai and @langchain/community/llms/bedrock as tracking packages so we can measure usage with angler ([#2053](https://github.com/newrelic/node-newrelic/pull/2053)) ([4830ea3](https://github.com/newrelic/node-newrelic/commit/4830ea3285726f8cc8fb60820c4cf2d3790e5250))
-
-#### Tests
-
-* Updated aws-sdk branch to main as the necessary code was merged. ([#2051](https://github.com/newrelic/node-newrelic/pull/2051)) ([1e52a5c](https://github.com/newrelic/node-newrelic/commit/1e52a5cd7a8acc8970dbdc6b1bf774c06aa6f5fb))
-
+### v11.14.0 (2024-03-20)
+
+#### Features
+
+* Added `guid` attribute to `TransactionError` events ([#2079](https://github.com/newrelic/node-newrelic/pull/2079)) ([3468fb1](https://github.com/newrelic/node-newrelic/commit/3468fb14635b10c30a9a814dc0d084aeacfd9e10))
+* Added instrumentation for `initializeUnorderedBulkOp`, and `initializeOrderedBulkOp` in mongodb 4+ ([#2086](https://github.com/newrelic/node-newrelic/pull/2086)) ([666ae6e](https://github.com/newrelic/node-newrelic/commit/666ae6ea4be8167748e31fe9b1d086aee5d0135d))
+* Added support for Mongo v5+ ([#2085](https://github.com/newrelic/node-newrelic/pull/2085)) ([00f6feb](https://github.com/newrelic/node-newrelic/commit/00f6febb4893ed2abe902644514af3ab629cdbc1))
+
+#### Security improvements
+
+* **deps:** bump follow-redirects from 1.15.5 to 1.15.6 ([#2078](https://github.com/newrelic/node-newrelic/pull/2078)) ([aa86482](https://github.com/newrelic/node-newrelic/commit/aa86482738ba6b17bf6c2c7362931a3ad57736dd))
+
+#### Documentation
+
+* Changed bug bounty URL ([#2081](https://github.com/newrelic/node-newrelic/pull/2081)) ([f4586d7](https://github.com/newrelic/node-newrelic/commit/f4586d71cbe9c886181fbfe4b414cf0f9d630873))
+
+#### Miscellaneous chores
+
+* Added instrumentation tracking class ([#2084](https://github.com/newrelic/node-newrelic/pull/2084)) ([07d7e7d](https://github.com/newrelic/node-newrelic/commit/07d7e7d50edf9cd8a1cd1b465b24bc589409c5dc))
+* **deps:** pin @newrelic/security-agent to 1.0.1 ([#2089](https://github.com/newrelic/node-newrelic/pull/2089)) ([e133c76](https://github.com/newrelic/node-newrelic/commit/e133c76a34f7d2af16610f00958651a6cff8824d))
+
+### v11.13.0 (2024-03-13)
+
+#### Features
+
+* Added AI Monitoring(AIM) for OpenAI, Amazon Bedrock, and Langchain.
+  * To enable set `config.ai_monitoring.enabled` or `NEW_RELIC_AI_MONITORING_ENABLED` to `true`.
+  * It is recommended for a full experience to set `config.span_events.max_samples_stored` to `10000`, `config.custom_insights_events.max_samples_stored` to `100000`, and `config.distributed_tracing.enabled` should not be set to false.
+  * **Note**: Enabling [high-security mode](https://docs.newrelic.com/docs/apm/agents/manage-apm-agents/configuration/high-security-mode/) will disable the AIM instrumentation and events. 
+* Added instrumentation for VectorStore.similaritySearch for langchain.js ([#2049](https://github.com/newrelic/node-newrelic/pull/2049)) ([3c50606](https://github.com/newrelic/node-newrelic/commit/3c50606a57a8dc18c91fe36e3b180bafd15a4cbc))
+* Added setLlmTokenCountCallback API endpoint to register a callback for calculating token count when none is provided ([#2065](https://github.com/newrelic/node-newrelic/pull/2065)) ([d2faf1a](https://github.com/newrelic/node-newrelic/commit/d2faf1a4942aacefd8b92e0bc2dc11bd8b687328))
+* Added token_count to LlmEmbedding and LlmChatCompletionMessage for openai ([#2061](https://github.com/newrelic/node-newrelic/pull/2061)) ([47a925e](https://github.com/newrelic/node-newrelic/commit/47a925eccce8e5b5d682b46277bbef5191f8b553))
+* Added tool_id to langchain error event ([#2064](https://github.com/newrelic/node-newrelic/pull/2064)) ([793abe8](https://github.com/newrelic/node-newrelic/commit/793abe8c9854b80fb1cf42f839a7db6a646cdc0b))
+
+#### Miscellaneous chores
+
+* Added flag for verbosity during docs publishing ([#2060](https://github.com/newrelic/node-newrelic/pull/2060)) ([fe0d41a](https://github.com/newrelic/node-newrelic/commit/fe0d41a86cba8da6173f5935e61c62b7dca75344))
+* Added some delays to docs publishing ([#2062](https://github.com/newrelic/node-newrelic/pull/2062)) ([a602fd4](https://github.com/newrelic/node-newrelic/commit/a602fd48e929437e4bc933c4ce276989013c53f1))
+* Changed casing of OpenAI in vendor property ([#2068](https://github.com/newrelic/node-newrelic/pull/2068)) ([64b4ca2](https://github.com/newrelic/node-newrelic/commit/64b4ca2750c9de8d9028fef515c15019e358a5d9))
+* Changed token_count to only use tokenCountCallback ([#2070](https://github.com/newrelic/node-newrelic/pull/2070)) ([66f94b0](https://github.com/newrelic/node-newrelic/commit/66f94b05aa7018af6fa1db1d2d87de9013f23a5b))
+* Removed langchain_instrumentation feature flag as the instrumentation is feature complete ([#2073](https://github.com/newrelic/node-newrelic/pull/2073)) ([925a463](https://github.com/newrelic/node-newrelic/commit/925a463c708b29c78567aecf78ac89ac226b7995))
+* updated @newrelic/aws-sdk and @newrelic/koa to latest ([#2074](https://github.com/newrelic/node-newrelic/pull/2074)) ([0747ca4](https://github.com/newrelic/node-newrelic/commit/0747ca4f0f6615e1fbfcc734a36059960facf23e))
+
+### v11.12.0 (2024-03-04)
+
+#### Features
+
+* Added instrumentation for `chain.stream` for langchain js. ([#2052](https://github.com/newrelic/node-newrelic/pull/2052)) ([03abfce](https://github.com/newrelic/node-newrelic/commit/03abfce666d3c48abd0994c44817bb5cbe8655a9))
+
+#### Miscellaneous chores
+
+* Added @azure/openai and @langchain/community/llms/bedrock as tracking packages so we can measure usage with angler ([#2053](https://github.com/newrelic/node-newrelic/pull/2053)) ([4830ea3](https://github.com/newrelic/node-newrelic/commit/4830ea3285726f8cc8fb60820c4cf2d3790e5250))
+
+#### Tests
+
+* Updated aws-sdk branch to main as the necessary code was merged. ([#2051](https://github.com/newrelic/node-newrelic/pull/2051)) ([1e52a5c](https://github.com/newrelic/node-newrelic/commit/1e52a5cd7a8acc8970dbdc6b1bf774c06aa6f5fb))
+
 ### v11.11.0 (2024-02-27)
 
 #### Features

package/README.md

@@ -234,7 +234,7 @@ If you have any questions, or to execute our corporate CLA, required if your con
 
 As noted in our [security policy](../../security/policy), New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.
 
-If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through [HackerOne](https://hackerone.com/newrelic).
+If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through [our bug bounty program](https://docs.newrelic.com/docs/security/security-privacy/information-security/report-security-vulnerabilities/).
 
 If you would like to contribute to this project, review [these guidelines](./CONTRIBUTING.md).
 

package/lib/errors/index.js

@@ -240,6 +240,7 @@ function _getErrorEventIntrinsicAttrs(transaction, errorClass, message, expected
     }
 
     attributes['nr.transactionGuid'] = transaction.id
+    attributes.guid = transaction.id
 
     if (transaction.port) {
       attributes.port = transaction.port

package/lib/instrumentation/mongodb/common.js

@@ -72,9 +72,13 @@ common.instrumentBulkOperation = function instrumentBulkOperation(shim, BulkOper
 common.instrumentDb = function instrumentDb(shim, Db) {
   if (Db && Db.prototype) {
     const proto = Db.prototype
-    shim.recordOperation(proto, DB_OPS, new OperationSpec({ callback: shim.LAST, opaque: true }))
+    shim.recordOperation(
+      proto,
+      DB_OPS,
+      new OperationSpec({ callback: shim.LAST, opaque: true, promise: true })
+    )
     // link to client.connect(removed in v4.0)
-    shim.recordOperation(Db, 'connect', new OperationSpec({ callback: shim.LAST }))
+    shim.recordOperation(Db, 'connect', new OperationSpec({ callback: shim.LAST, promise: true }))
   }
 }
 
@@ -133,7 +137,7 @@ common.makeBulkDescFunc = function makeBulkDescFunc(shim) {
  *
  * @param {Shim} shim instance of shim
  * @param {object} instrumenter instance of mongo APM class
- * @param {object} [options={}] provide command names to skip updating host/port as they are unrelated to the active query.  This is only in v3 because after every command is runs `endSessions` which runs on the admin database
+ * @param {object} [options] provide command names to skip updating host/port as they are unrelated to the active query.  This is only in v3 because after every command is runs `endSessions` which runs on the admin database
  */
 common.captureAttributesOnStarted = function captureAttributesOnStarted(
   shim,
@@ -214,7 +218,6 @@ function setHostPort(shim, connStr, db, client) {
  */
 function getInstanceAttributeParameters(shim, mongo) {
   let params
-
   if (mongo?.s?.topology) {
     shim.logger.trace('Adding datastore instance attributes from mongo.s.db + mongo.s.topology')
     const databaseName = mongo?.s?.db?.databaseName || mongo?.s?.namespace?.db || null
@@ -224,6 +227,10 @@ function getInstanceAttributeParameters(shim, mongo) {
     const databaseName = mongo?.s?.db?.databaseName || null
     const hosts = mongo.s.db.s.client.s.options.hosts
     params = getParametersFromHosts(hosts, databaseName)
+  } else if (mongo?.s?.db?.client?.topology) {
+    const databaseName = mongo?.s?.namespace?.db
+    const topology = mongo.s.db.client.topology
+    params = getParametersFromTopology(topology, databaseName)
   } else {
     shim.logger.trace('Could not find datastore instance attributes.')
     params = new DatastoreParameters()
@@ -272,6 +279,11 @@ function getParametersFromTopology(conf, database) {
     ;[{ host, port }] = conf.s.options.servers
   }
 
+  // hosts is an array but we will always pull the first for consistency
+  if (conf?.s?.options?.hosts?.length) {
+    ;[{ host, port }] = conf.s.options.hosts
+  }
+
   // host is a domain socket. set host as localhost and use the domain
   // socket host as the port
   if (host && host.endsWith('.sock')) {
@@ -280,7 +292,7 @@ function getParametersFromTopology(conf, database) {
   }
 
   return new DatastoreParameters({
-    host: host,
+    host,
     port_path_or_id: port,
     database_name: database
   })

package/lib/instrumentation/mongodb/v4-mongo.js

@@ -6,7 +6,13 @@
 'use strict'
 
 const { OperationSpec } = require('../../shim/specs')
-const { instrumentCollection, instrumentCursor, instrumentDb, parseAddress } = require('./common')
+const {
+  instrumentBulkOperation,
+  instrumentCollection,
+  instrumentCursor,
+  instrumentDb,
+  parseAddress
+} = require('./common')
 
 /**
  * parser used to grab the collection and operation
@@ -18,8 +24,11 @@ function queryParser(operation) {
   let collection = this.collectionName || 'unknown'
 
   // cursor methods have collection on namespace.collection
-  if (this.namespace && this.namespace.collection) {
+  if (this?.namespace?.collection) {
     collection = this.namespace.collection
+    // (un)ordered bulk operations have collection on different key
+  } else if (this?.s?.collection?.collectionName) {
+    collection = this.s.collection.collectionName
   }
 
   return { operation, collection }
@@ -88,4 +97,5 @@ module.exports = function instrument(shim, mongodb) {
   instrumentCursor(shim, mongodb.AggregationCursor)
   instrumentCollection(shim, mongodb.Collection)
   instrumentDb(shim, mongodb.Db)
+  instrumentBulkOperation(shim, shim.require('./lib/bulk/common'))
 }

package/lib/instrumentation-descriptor.js

@@ -0,0 +1,186 @@
+/*
+ * Copyright 2024 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const IdGen = require('./util/idgen')
+const idGen = new IdGen()
+
+/**
+ * @typedef {function} InstrumentationOnRequire
+ * @param {Shim} shim The shim instance to use for the instrumentation.
+ * @param {object} resolvedNodule The module being instrumented as returned by
+ * Node's `require` function.
+ * @param {string} moduleName The simple name of the module, i.e. the value
+ * passed to the `require` function.
+ * @throws {Error|object}
+ */
+
+/**
+ * @typedef {function} InstrumentationOnError
+ * @param {Error|object} error The error thrown by `onRequire` when there was
+ * an issue registering the instrumentation.
+ */
+
+/* eslint-disable jsdoc/require-property-description */
+/**
+ * @typedef {object} InstrumentationDescriptorParams
+ * @property {string} absolutePath
+ * @property {string} module
+ * @property {string} moduleName
+ * @property {InstrumentationOnError} onError
+ * @property {InstrumentationOnRequire} onRequire
+ * @property {string} resolvedName
+ * @property {string} type
+ */
+
+/**
+ * Describes the configuration for an instrumentation. An instrumentation
+ * is what `newrelic` uses to wrap Node.js modules. In particular, a description
+ * details the name of the module, the path on disk to the module, and the
+ * hooks (`onRequire` and `onError`) to apply to the module.
+ */
+class InstrumentationDescriptor {
+  /**
+   * Utility/generic module.
+   * @type {string}
+   */
+  static TYPE_GENERIC = 'generic'
+
+  /**
+   * @private
+   * @type {string}
+   */
+  static TYPE_CONGLOMERATE = 'conglomerate'
+
+  /**
+   * Database module, such as the MongoDB or MySQL drivers.
+   * @type {string}
+   */
+  static TYPE_DATASTORE = 'datastore'
+
+  /**
+   * Messaging module, such as AMQP.
+   * @type {string}
+   */
+  static TYPE_MESSAGE = 'message'
+
+  /**
+   * Promise module, such as Bluebird.
+   * @type {string}
+   */
+  static TYPE_PROMISE = 'promise'
+
+  /**
+   * @private
+   * @type {string}
+   */
+  static TYPE_TRANSACTION = 'transaction'
+
+  /**
+   * Web server framework module, such as Express or Fastify.
+   * @type {string}
+   */
+  static TYPE_WEB_FRAMEWORK = 'web-framework'
+
+  /**
+   * Used to load supportability metrics on installed versions of packages
+   * that the Node.js agent does not instrument (e.g. OTEL instrumentation or
+   * top logging libraries).
+   * @type {string}
+   */
+  static TYPE_TRACKING = 'tracking'
+
+  /**
+   * The type of the module being instrumented. See the static `TYPE_` fields.
+   * @type {string|null}
+   */
+  type
+
+  /**
+   * The name of the module being instrumented, i.e. the string used to require
+   * the module. This must map to a directory in `lib/instrumentations` which
+   * contains an `nr-hooks.js` file.
+   *
+   * This takes precedence over `moduleName`.
+   * @type {string}
+   */
+  module
+
+  /**
+   * The name of the module being instrumented, i.e. the string used to require
+   * the module. This must map to a JavaScript file of the same name in the
+   * `lib/instrumentations` directory.
+   * @type {string}
+   */
+  moduleName
+
+  /**
+   * The absolute path to the module to instrument. This should only be set
+   * when the module being instrumented does not reside in a `node_modules`
+   * directory; for example, when someone is instrumenting a module of their
+   * own through the public API.
+   *
+   * The `moduleName` property still needs to be set to the simple name, i.e.
+   * the string passed to `require`, for instrumentation tracking purposes.
+   *
+   * Note: this value takes precedence over `moduleName`.
+   */
+  absolutePath
+
+  /**
+   * The fully resolved path to the module, e.g. `/opt/app/node_modules/foo`.
+   * If the module is a core module, the special value `.` should be used.
+   * @type {string}
+   */
+  resolvedName
+
+  /**
+   * Hook to invoke when the module is required. This is the actual
+   * implementation of the instrumentation.
+   * @type {InstrumentationOnRequire}
+   */
+  onRequire
+
+  /**
+   * Hook to invoke when the `onRequire` hook throws an error.
+   * @type {InstrumentationOnError}
+   */
+  onError
+
+  /**
+   * @type {number}
+   */
+  #id
+
+  /* eslint-disable jsdoc/require-param-description */
+  /**
+   * @param {InstrumentationDescriptorParams} params
+   */
+  constructor(params) {
+    this.absolutePath = params.absolutePath
+    this.module = params.module
+    this.moduleName = params.moduleName
+    this.onError = params.onError
+    this.onRequire = params.onRequire
+    this.resolvedName = params.resolvedName
+    this.type = params.type
+
+    this.#id = idGen.idFor(this.moduleName)
+  }
+
+  /**
+   * Identifier for the instrumentation. Used by the internal instrumentation
+   * tracker to distinguish between different instrumentations targeting the
+   * same module.
+   *
+   * @returns {number} The identifier.
+   */
+  get instrumentationId() {
+    return this.#id
+  }
+}
+
+module.exports = InstrumentationDescriptor

package/lib/instrumentation-tracker.js

@@ -0,0 +1,222 @@
+/*
+ * Copyright 2024 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const InstrumentationDescriptor = require('./instrumentation-descriptor')
+
+/**
+ * @typedef {object} TrackedItemMeta
+ * @property {boolean} instrumented Indicates if the instrumentation
+ * has been successfully applied.
+ * @property {boolean|undefined} didError Indicates if the instrumentation
+ * application resulted in an error or not.
+ */
+
+/**
+ * Represents tracked instrumentations in the {@link InstrumentationTracker}.
+ *
+ * @private
+ */
+class TrackedItem {
+  /**
+   * @type {InstrumentationDescriptor}
+   */
+  instrumentation
+
+  /**
+   * @type {TrackedItemMeta}
+   */
+  meta
+
+  constructor(params) {
+    this.instrumentation = params.instrumentation
+    this.meta = params.meta
+  }
+}
+
+/**
+ * The instrumentation tracker is used to keep track of
+ * {@link InstrumentationDescriptor} instances in relation to modules that
+ * are being instrumented. The general process looks like:
+ *
+ * 1. We register an instrumentation with a simple name like `pino`. This
+ * "instrumentation" includes things like the `onRequire` and `onError`
+ * callbacks. In this context, "instrumentation" and "hook" are interchangeable
+ * terms.
+ *
+ * 2. Upon `require(<simple_name>)`, we hit `shimmer._postLoad` which will give
+ * us the fully resolved path to the module being loaded.
+ *
+ * 3. `_postLoad` will utilize the previously registered instrumentation
+ * information to determine if there are any callbacks for the module being
+ * loaded. If so, it will attempt to run the callbacks.
+ *
+ * 4. At this point we need to keep track of which simple name + fully resolved
+ * path has callbacks associated with it, and if the error callback was invoked.
+ * When a subsequent load of the same simple name + fully resolved path
+ * combination is encountered, we need to append that to the tracked hooks.
+ * Or, if the previous hook failed, provide a way for the loading algorithm
+ * to learn about that so that it can skip doing unnecessary work.
+ *
+ * The `InstrumentationTracker` object provides utility methods to facilitate
+ * that process.
+ *
+ * @private
+ */
+class InstrumentationTracker {
+  #tracked = new Map()
+
+  get [Symbol.toStringTag]() {
+    return 'InstrumentationTracker'
+  }
+
+  /**
+   * Get all tracked instrumentations for the named module.
+   *
+   * @param {string} moduleName The simple name for the module, e.g. "pino".
+   *
+   * @returns {TrackedItem[]} All tracked items for the module.
+   */
+  getAllByName(moduleName) {
+    return this.#tracked.get(moduleName)
+  }
+
+  /**
+   * Get a specific tracked item for a module. This allows the
+   * {@link setHookSuccess} and {@link setHookFailure} methods to be used.
+   *
+   * @param {string} moduleName The simple name for the module, e.g. "pino".
+   * @param {InstrumentationDescriptor} instrumentation The instrumentation
+   * descriptor that is contained within the tracked item.
+   *
+   * @returns {TrackedItem|undefined} The full tracked item that includes the
+   * passed in descriptor along with the metadata about the instrumentation.
+   */
+  getTrackedItem(moduleName, instrumentation) {
+    const items = this.getAllByName(moduleName)
+    for (const item of items) {
+      /* istanbul ignore else */
+      if (item.instrumentation === instrumentation) {
+        return item
+      }
+    }
+  }
+
+  /**
+   * The primary entrypoint to the tracker. It registers the basic information
+   * about an instrumentation prior to the to-be-instrumented module being
+   * loaded. If this method is not used first, other methods will throw because
+   * they will not be able to find any tracked items.
+   *
+   * @param {string} moduleName The simple name of the module being
+   * instrumented, e.g. "pino". That is, whatever is passed to the `require`
+   * function.
+   * @param {InstrumentationDescriptor} instrumentation The initial descriptor
+   * for the module being instrumented.
+   */
+  track(moduleName, instrumentation) {
+    const tracked = this.#tracked.get(moduleName)
+    if (tracked === undefined) {
+      this.#tracked.set(moduleName, [
+        new TrackedItem({ instrumentation, meta: { instrumented: false, didError: undefined } })
+      ])
+      return
+    }
+
+    let found
+    for (const t of tracked) {
+      if (t.instrumentation.instrumentationId === instrumentation.instrumentationId) {
+        return
+      }
+    }
+    /* istanbul ignore else */
+    if (found === undefined) {
+      tracked.push(
+        new TrackedItem({ instrumentation, meta: { instrumented: false, didError: undefined } })
+      )
+    }
+  }
+
+  /**
+   * Update the metadata for a tracked item to indicate that the hook failed.
+   *
+   * @param {TrackedItem} trackedItem The item to update.
+   */
+  setHookFailure(trackedItem) {
+    trackedItem.meta.instrumented = false
+    trackedItem.meta.didError = true
+  }
+
+  /**
+   * Update the metadata for a tracked item to indicate that the hook succeeded.
+   *
+   * @param {TrackedItem} trackedItem The item to update.
+   */
+  setHookSuccess(trackedItem) {
+    trackedItem.meta.instrumented = true
+    trackedItem.meta.didError = false
+  }
+
+  /**
+   * After a module has been loaded, via `require` or `import`, the tracked
+   * instrumentation for that module must have its `resolvedName` property
+   * updated. The `resolvedName` is used to uniquely identify instances of the
+   * module. Being able to uniquely identify instances is crucial to being able
+   * to instrument all loaded instances.
+   *
+   * @param {string} moduleName The simple name of the module, e.g. "pino".
+   * @param {string} resolvedName The fully resolved file system path to the
+   * module instance, e.g. "/opt/app/node_modules/pino".
+   *
+   * @throws {Error} If the provided `moduleName` is not present in the tracker.
+   */
+  setResolvedName(moduleName, resolvedName) {
+    const items = this.#tracked.get(moduleName)
+    if (items === undefined) {
+      throw Error(`module not tracked: ${moduleName}`)
+    }
+
+    const missingResolvedName = []
+    for (const item of items) {
+      if (item.instrumentation.resolvedName === undefined) {
+        missingResolvedName.push(item)
+      } else if (item.instrumentation.resolvedName === resolvedName) {
+        // We already have this specific instance of the module tracked.
+        // So we don't need to do anything.
+        return
+      }
+    }
+
+    // eslint-disable-next-line sonarjs/no-small-switch
+    switch (missingResolvedName.length) {
+      case 0: {
+        // We have encountered a new instance of the module. Therefore, we
+        // need to clone an existing instrumentation, but apply a different
+        // `resolvedName` to it.
+        //
+        // This happens when there is a dependency tree like:
+        // + `/opt/app/node_modules/foo`
+        // + `/opt/app/node_modules/transitive-dep/node_modules/foo`
+        const item = items[0]
+        this.track(
+          moduleName,
+          new InstrumentationDescriptor({ ...item.instrumentation, resolvedName })
+        )
+        break
+      }
+
+      default: {
+        // Add the same name to all found instrumentations. This definitely
+        // happens when the security agent is enabled.
+        missingResolvedName.forEach((item) => {
+          item.instrumentation.resolvedName = resolvedName
+        })
+      }
+    }
+  }
+}
+
+module.exports = InstrumentationTracker

package/lib/util/idgen.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2024 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+class IdGenerator {
+  #tracked = new Map()
+
+  /**
+   * Get the next available identifier for the provided `name`.
+   *
+   * @param {string} name The label to get an id for.
+   *
+   * @returns {number} The id.
+   */
+  idFor(name) {
+    const key = Symbol.for(name)
+    let val = this.#tracked.get(key)
+    if (val === undefined) {
+      val = 0
+    } else {
+      val += 1
+    }
+    this.#tracked.set(key, val)
+    return val
+  }
+}
+
+module.exports = IdGenerator

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newrelic",
-  "version": "11.13.0",
+  "version": "11.14.0",
   "author": "New Relic Node.js agent team <nodejs@newrelic.com>",
   "license": "Apache-2.0",
   "contributors": [
@@ -196,7 +196,7 @@
     "@newrelic/aws-sdk": "^7.3.0",
     "@newrelic/koa": "^9.0.0",
     "@newrelic/ritm": "^7.2.0",
-    "@newrelic/security-agent": "^1.0.1",
+    "@newrelic/security-agent": "1.0.1",
     "@newrelic/superagent": "^7.0.1",
     "@tyriar/fibonacci-heap": "^2.0.7",
     "concat-stream": "^2.0.0",