newrelic 13.3.2 → 13.4.0

package/lib/subscribers/meta-subscriber.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+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.
+ * @property {string} packageName The package name being instrumented.
+ * 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
+ */
+class MetaSubscriber {
+  constructor({ agent, logger, packageName, channelName, channels, events, callback }) {
+    this.config = agent.config
+    this.packageName = packageName
+    this.id = `orchestrion:${packageName}:${channelName}`
+    this.subscribers = channels.map((name) => {
+      const subscriber = new Subscriber({ agent, logger, packageName, channelName: name })
+      subscriber.events = events
+      subscriber.handler = this.handler.bind(subscriber)
+      if (callback !== null) {
+        subscriber.callback = callback
+      }
+      return subscriber
+    })
+  }
+
+  get enabled() {
+    return this.config.instrumentation[this.packageName].enabled === true
+  }
+
+  enable() {
+    for (const subscriber of this.subscribers) {
+      subscriber.enable()
+    }
+  }
+
+  disable() {
+    for (const subscriber of this.subscribers) {
+      subscriber.disable()
+    }
+  }
+
+  subscribe() {
+    for (const subscriber of this.subscribers) {
+      subscriber.subscribe()
+    }
+  }
+
+  unsubscribe() {
+    for (const subscriber of this.subscribers) {
+      subscriber.unsubscribe()
+    }
+  }
+}
+
+module.exports = MetaSubscriber

package/lib/subscribers/openai/base.js

@@ -10,12 +10,38 @@ const Subscriber = require('../base')
 class OpenAISubscriber extends Subscriber {
   constructor({ agent, logger, channelName }) {
     super({ agent, logger, packageName: 'openai', channelName })
-    this.events = ['asyncEnd']
+    this.events = ['asyncEnd', 'end']
   }
 
   get enabled() {
     return super.enabled && this.config.ai_monitoring?.enabled
   }
+
+  /**
+   * Temporary fix as `tracePromise` wraps the promise in a native one.
+   * We are now wrapping all openai functions in a `traceSync` call.
+   * Then we wrap the promise here so it returns the custom promise.
+   * OpenAI has a [custom promise](https://github.com/openai/openai-node/blob/master/src/core/api-promise.ts).
+   * see: https://github.com/newrelic/node-newrelic/issues/3379
+   * see: https://github.com/nodejs/node/issues/59936
+   * @param {object} data the data associated with the `end` event
+   */
+  end(data) {
+    const promise = data?.result
+    if (!promise.then) {
+      return promise
+    }
+
+    return promise.then((result) => {
+      data.result = result
+      this.channel.asyncEnd.publish(data)
+      return result
+    }).catch((err) => {
+      data.error = err
+      this.channel.asyncEnd.publish(data)
+      return err
+    })
+  }
 }
 
 module.exports = OpenAISubscriber

package/lib/subscribers/openai/config.js

@@ -16,7 +16,7 @@ module.exports = {
           functionQuery: {
             className: 'Completions',
             methodName: 'create',
-            kind: 'Async'
+            kind: 'Sync'
           }
         },
         {
@@ -25,7 +25,7 @@ module.exports = {
           functionQuery: {
             className: 'Completions',
             methodName: 'create',
-            kind: 'Async'
+            kind: 'Sync'
           }
         }
       ]
@@ -39,7 +39,7 @@ module.exports = {
           functionQuery: {
             className: 'Responses',
             methodName: 'create',
-            kind: 'Async'
+            kind: 'Sync'
           }
         }
       ]
@@ -53,7 +53,7 @@ module.exports = {
           functionQuery: {
             className: 'APIClient',
             methodName: 'makeRequest',
-            kind: 'Async'
+            kind: 'Sync'
           }
         },
         {
@@ -62,7 +62,7 @@ module.exports = {
           functionQuery: {
             className: 'OpenAI',
             methodName: 'makeRequest',
-            kind: 'Async'
+            kind: 'Sync'
           }
         }
       ]
@@ -76,7 +76,7 @@ module.exports = {
           functionQuery: {
             className: 'Embeddings',
             methodName: 'create',
-            kind: 'Async'
+            kind: 'Sync'
           }
         }
       ]

package/lib/subscribers/openai/utils.js

@@ -41,7 +41,7 @@ function getMessageFromResponse(response) {
  * Parses all messages from the OpenAI request object.
  *
  * @param {object} request The OpenAI SDK request object
- * @param logger
+ * @param {Logger} logger instance
  * @returns {Array<object>} an array of message objects with fields `content` and `role`
  */
 function getMessagesFromRequest(request, logger) {
@@ -95,7 +95,7 @@ function recordEvent({ agent, type, msg }) {
  * @param {object} params input params
  * @param {Agent} params.agent NR agent instance
  * @param {Transaction} params.transaction active transaction
- * @param params.version
+ * @param {string} params.version package version
  */
 function addLlmMeta({ agent, transaction, version }) {
   TRACKING_METRIC = `${TRACKING_METRIC}/${version}`
@@ -112,13 +112,13 @@ function addLlmMeta({ agent, transaction, version }) {
  *
  * @param {object} params input params
  * @param {Agent} params.agent NR agent instance
+ * @param {object} params.headers request headers
+ * @param {Logger} params.logger logger instance
  * @param {TraceSegment} params.segment active segment from chat completion
  * @param {object} params.request chat completion params
  * @param {object} params.response chat completion response
  * @param {boolean} [params.err] err if it exists
  * @param {Transaction} params.transaction active transaction
- * @param params.headers
- * @param params.logger
  */
 function recordChatCompletionMessages({
   agent,
@@ -189,11 +189,10 @@ function recordChatCompletionMessages({
 
 /**
  * Checks if we should skip instrumentation.
- * Currently, it checks if `ai_monitoring.enabled` is true
- * and the package version >= 4.0.0
+ * Currently, just checks if `ai_monitoring.enabled` is true.
  *
  * @param {object} config agent config
- * @param logger
+ * @param {Logger} logger instance
  * @returns {boolean} flag if instrumentation should be skipped
  */
 function shouldSkipInstrumentation(config, logger) {
@@ -212,14 +211,13 @@ function shouldSkipInstrumentation(config, logger) {
  * messages.
  * @param {object} params input params
  * @param {Agent} params.agent NR agent instance
- * @param {Shim} params.shim the current shim instance
+ * @param {object} params.headers request headers
+ * @param {object} params.logger logger instance
  * @param {object} params.request chat completion params
  * @param {object} params.response chat completion response
  * @param {TraceSegment} params.segment active segment from chat completion
  * @param {Transaction} params.transaction active transaction
- * @param {Error} params.err error if it exists
- * @param params.headers
- * @param params.logger
+ * @param {Error} [params.err] error if it exists
  */
 function instrumentStream({ agent, headers, logger, request, response, segment, transaction, err = null }) {
   if (!agent.config.ai_monitoring.streaming.enabled) {

package/lib/subscribers/propagation.js

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+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.
+ */
+class PropagationSubscriber extends Subscriber {
+  constructor({ agent, logger, packageName, channelName, callback }) {
+    super({ agent, logger, packageName, channelName })
+    this.callback = callback
+    this.propagateTx = true
+    this.events = ['asyncStart', 'asyncEnd']
+  }
+
+  enable() {
+    super.enable()
+    this.channel.asyncStart.bindStore(this.store, (data) => {
+      const { transaction, segment } = data
+      const ctx = this.agent.tracer.getContext()
+
+      if (!(transaction && segment)) {
+        this.logger.trace('No active transaction/segment, returning existing context')
+        return ctx
+      }
+      const newCtx = ctx.enterSegment({ transaction, segment })
+      return newCtx
+    })
+  }
+
+  disable() {
+    super.disable()
+    this.channel.asyncStart.unbindStore(this.store)
+  }
+}
+
+module.exports = PropagationSubscriber

package/lib/timer.js

@@ -220,7 +220,7 @@ Timer.prototype.startedRelativeTo = function startedRelativeTo(other) {
 /**
  * Returns true if this timer ends after the other.
  *
- * @param other
+ * @param {Timer} other other timer
  */
 Timer.prototype.endsAfter = function compare(other) {
   return this.getDurationInMillis() + this.start > other.getDurationInMillis() + other.start

package/lib/transaction/dt-payload.js

@@ -15,7 +15,7 @@ module.exports = class DistributedTracePayload {
    * The class responsible for producing distributed trace payloads.
    * Created by calling {@link TransactionHandle#_createDistributedTracePayload}.
    *
-   * @param payload
+   * @param {Object} payload DT payload
    * @class
    */
   constructor(payload) {

package/lib/transaction/handle.js

@@ -14,8 +14,8 @@ class TransactionHandle {
    * A light representation of a transaction instance, returned by calling
    * {@link API#getTransaction}.
    *
-   * @param transaction
-   * @param metrics
+   * @param {Transaction} transaction the associated transaction
+   * @param {Metrics} metrics class instance
    * @class
    */
   constructor(transaction, metrics) {
@@ -26,7 +26,7 @@ class TransactionHandle {
   /**
    * End the transaction.
    *
-   * @param  {Function} callback
+   * @param {Function} callback The function to call after ending the transaction.
    */
   end(callback) {
     const tx = this._transaction.end()
@@ -57,11 +57,10 @@ class TransactionHandle {
    * W3C TraceContext format is preferred over the NewRelic DT format.
    * NewRelic DT format will be used if no `traceparent` header is found.
    *
-   * @param @param {string} [transportType='Unknown'] - The transport type that delivered the trace.
-   * @param transportType
+   * @param {string} [transportType] - The transport type that delivered the trace; defaults to 'Unknown'.
    * @param {object} headers - Headers to search for supported formats. Keys must be lowercase.
    */
-  acceptDistributedTraceHeaders(transportType, headers) {
+  acceptDistributedTraceHeaders(transportType = 'Unknown', headers) {
     incrementApiSupportMetric(this._metrics, 'acceptDistributedTraceHeaders')
     return this._transaction.acceptDistributedTraceHeaders(transportType, headers)
   }
@@ -69,7 +68,7 @@ class TransactionHandle {
   /**
    * Inserts distributed trace headers into the provided headers map.
    *
-   * @param {object} headers
+   * @param {object} headers DT headers
    */
   insertDistributedTraceHeaders(headers) {
     incrementApiSupportMetric(this._metrics, 'insertDistributedTraceHeaders')
@@ -82,8 +81,8 @@ module.exports = TransactionHandle
 /**
  *
  * @private
- * @param metrics
- * @param functionName
+ * @param {Metrics} metrics class instance
+ * @param {string} functionName name of function to increment the metric of
  */
 function incrementApiSupportMetric(metrics, functionName) {
   if (!metrics) {

package/lib/transaction/name-state.js

@@ -29,10 +29,10 @@ const STATUS_CODE_NAMES = {
 /**
  * Manages transaction names using a stack of paths.
  *
- * @param prefix
- * @param verb
- * @param delimiter
- * @param path
+ * @param {string} prefix metric prefix
+ * @param {string} verb HTTP verb
+ * @param {string} delimiter delimiter character
+ * @param {string} path path element
  * @class
  */
 function NameState(prefix, verb, delimiter, path) {
@@ -72,7 +72,7 @@ NameState.prototype.markPath = function markPath() {
 /**
  * Sets the metric prefix (i.e. Expressjs).
  *
- * @param prefix
+ * @param {string} prefix metric prefix
  */
 NameState.prototype.setPrefix = function setPrefix(prefix) {
   if (this._frozen) {
@@ -89,7 +89,7 @@ NameState.prototype.setPrefix = function setPrefix(prefix) {
 /**
  * Sets the HTTP verb (i.e. GET/POST/PUT)
  *
- * @param verb
+ * @param {string} verb HTTP verb
  */
 NameState.prototype.setVerb = function setVerb(verb) {
   if (!this._frozen) {
@@ -100,7 +100,7 @@ NameState.prototype.setVerb = function setVerb(verb) {
 /**
  * Sets the delimiter character used to separate the http verb from the path.
  *
- * @param delimiter
+ * @param {string} delimiter delimiter character
  */
 NameState.prototype.setDelimiter = function setDelimiter(delimiter) {
   if (!this._frozen) {
@@ -115,8 +115,8 @@ NameState.prototype.isEmpty = function isEmpty() {
 /**
  * Pushes a new path element onto the naming stack.
  *
- * @param path
- * @param params
+ * @param {string} path path element
+ * @param {Object} params to add to pathStack
  */
 NameState.prototype.appendPath = function appendPath(path, params) {
   if (!this._frozen && path != null) {
@@ -134,8 +134,8 @@ NameState.prototype.appendPath = function appendPath(path, params) {
  * Pushes a new path element onto the naming stack if the stack is
  * empty.
  *
- * @param path
- * @param params
+ * @param {string} path path element
+ * @param {Object} params to add with appendPath
  */
 NameState.prototype.appendPathIfEmpty = function appendPathIfEmpty(path, params) {
   if (!this._frozen && this.isEmpty()) {

package/lib/transaction/trace/segment.js

@@ -138,7 +138,7 @@ TraceSegment.prototype.setNameFromTransaction = function setNameFromTransaction(
  * finally, marking the trace segment as being a web segment copies the
  * segment's parameters onto the transaction.
  * @param {Transaction} transaction The transaction to which this segment will be bound.
- * @param obfuscatedUrl
+ * @param {object} obfuscatedUrl The obfuscated URL for the request.
  */
 TraceSegment.prototype.markAsWeb = function markAsWeb(transaction, obfuscatedUrl) {
   this.setNameFromTransaction(transaction)
@@ -270,11 +270,10 @@ function getExclusiveDurationInMillis(trace) {
  * @param {string} params.protocol protocol of request(i.e. `http:`, `grpc:`)
  * @param {string} params.hostname hostname of request(no port)
  * @param {string} params.host host of request(hostname + port)
- * @param [string] params.port port of request if applicable
+ * @param {string} params.port port of request if applicable
  * @param {string} params.path uri of request
  * @param {string} [params.method] method of request
  * @param {object} [params.queryParams] query parameters of request
- * @param params.port
  */
 TraceSegment.prototype.captureExternalAttributes = function captureExternalAttributes({
   protocol,

package/lib/util/attribute-types.js

@@ -11,7 +11,7 @@ const VALID_ATTR_TYPES = new Set(['string', 'number', 'boolean'])
  * Checks incoming attribute value against valid types:
  * string, number, & boolean.
  *
- * @param {*} val
+ * @param {*} val value to check type of
  * @returns {boolean}
  */
 function isValidType(val) {

package/lib/util/byte-limit.js

@@ -21,7 +21,7 @@ function isValidLength(str, limit) {
  * 0 if the string is at the limit
  * <1 if the string is shorter than the limit
  *
- * @param {string} str
+ * @param {string} str - Object key name or value
  * @param {number} limit - String byte limit
  */
 function compareLength(str, limit) {

package/lib/util/cat.js

@@ -32,11 +32,11 @@ const MATCH_CAT_APP_DATA_HEADER = new RegExp(
 /**
  * Decodes the CAT id and transaction headers from incoming request
  *
- * @param {object} headers incoming headers
- * @param id
- * @param transactionId
+ * @param {object} id CAT id
+ * @param {object} transactionId transaction header id
  * @param {string} encKey config.encoding_key used to decode CAT headers
- * @param {object} { externalId, externalTransaction }
+ *
+ * @returns {object} { externalId, externalTransaction }
  */
 cat.parseCatData = function parseCatData(id, transactionId, encKey) {
   if (!encKey) {
@@ -109,10 +109,10 @@ cat.assignCatToTransaction = function assignCatToTransaction(
  * for incoming requests
  *
  * @param {object} config agent config
- * @param {Transaction} transaction
- * @param {string} contentLength
+ * @param {Transaction} transaction current transaction
+ * @param {string} contentLength length of content
  * @param {boolean} useMqHeaders flag to return proper headers for MQ compliance
- * @returns {object} { key, data} to add as header
+ * @returns {object} { key, data } to add as header
  */
 cat.encodeAppData = function encodeAppData(config, transaction, contentLength, useMqHeaders) {
   let appData = null
@@ -147,7 +147,7 @@ cat.encodeAppData = function encodeAppData(config, transaction, contentLength, u
  * Adds CAT headers to outbound request.
  *
  * @param {object} config agent config
- * @param {Transaction} transaction
+ * @param {Transaction} transaction current transaction
  * @param {object} headers object that contains headers the agent is adding to client request
  * @param {boolean} useMqHeaders flag to return proper headers for MQ compliance
  */
@@ -189,9 +189,9 @@ cat.addCatHeaders = function addCatHeaders(config, transaction, headers, useMqHe
 
 /**
  * Find the CAT id, transaction, app data headers
- * from the headers of either HTTP or MQ request
+ * from the headers of either HTTP or MQ request.
  *
- * @param {object} headers
+ * @param {object} headers HTTP/MQ headers
  * @returns {object} { id, transactionId, appData }
  */
 cat.extractCatHeaders = function extractCatHeaders(headers) {
@@ -220,8 +220,7 @@ cat.extractCatHeaders = function extractCatHeaders(headers) {
  * Extracts the account Id from CAT data and verifies if it is
  * a trusted account id
  *
- * @param {object} CAT data
- * @param data
+ * @param {object} data CAT data
  * @param {Array} trustedAccounts from config
  * @returns {boolean}
  */
@@ -240,7 +239,8 @@ cat.isTrustedAccountId = function isTrustedAccountId(data, trustedAccounts) {
  *
  * @param {object} config agent config
  * @param {string} obfAppData encoded app data to parse and use
- * @param {Array} decoded app data header
+ *
+ * @returns {Array} decoded app data header
  */
 cat.parseAppData = function parseAppData(config, obfAppData) {
   if (!config.encoding_key) {

package/lib/util/flatten.js

@@ -16,8 +16,8 @@ exports.keys = flatKeys
  * @private
  * @param {object} result Object to place key-value pairs into, normally called with `{}`.
  * @param {string} prefix Prefix for keys, normally called with `''`.
- * @param seen
  * @param {object} obj    Object to be flattened.
+ * @param {Array} seen    Array of seen objects to prevent circular references.
  * @returns {object} Object with flattened key-value pairs
  */
 function flatten(result, prefix, obj, seen) {
@@ -45,8 +45,7 @@ function flatten(result, prefix, obj, seen) {
  * @private
  * @param {object}  obj       - The object to get the flat keys of.
  * @param {string}  prefix    - A prefix for the keys, usually `''`.
- * @param arrayIdxs
- * @param {boolean}    arrayIdx  - Flag indicating if array indexes should be iterated.
+ * @param {boolean}    arrayIdxs  - Flag indicating if array indexes should be iterated.
  * @returns {Array.<string>} An array of keys names.
  */
 function flatKeys(obj, prefix, arrayIdxs) {

package/lib/util/is-absolute-path.js

@@ -19,7 +19,7 @@ module.exports = function isAbsolutePath(target) {
   }
 
   const suffix = target.slice(-4)
-  /* eslint-disable-next-line */
+
   if (suffix.slice(-3) !== '.js' && suffix !== '.cjs' && suffix !== '.mjs') {
     return false
   }

package/lib/util/is-string.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+/**
+ * Tests if argument passed in is a string or String object
+ * @param {*} data to check if it is a string
+ * @returns {boolean} if string or string object
+ */
+module.exports = function isString(data) {
+  return typeof data === 'string' || data instanceof String
+}

package/lib/util/logger.js

@@ -253,14 +253,14 @@ Logger.prototype._read = function _read() {
 }
 
 /**
- * For performance reasons we do not support %j because we will have
+ * For performance reasons, we do not support %j because we will have
  * already converted the objects to strings.
- * Returns a boolean representing the status of the write
- * (success/failure)
  *
- * @param level
- * @param args
- * @param extra
+ * @param {string} level log entry level
+ * @param {Array} args arguments to stringify
+ * @param {Object} extra data to log
+ *
+ * @returns {boolean} True if the log was written successfully, false otherwise.
  */
 Logger.prototype.write = function write(level, args, extra) {
   if (this._nestedLog) {

package/lib/util/stream-sink.js

@@ -26,7 +26,7 @@ const util = require('util')
  * contract and the callback will be fired when the stream has been completely
  * read.
  *
- * @param callback
+ * @param {function} callback Function to call when stream has been read.
  */
 function StreamSink(callback) {
   EventEmitter.call(this)

package/lib/utilization/docker-info.js

@@ -58,9 +58,10 @@ function recordBootIdError(agent) {
 /**
  * Utility function to parse a Docker boot id from a cgroup proc file.
  *
- * @param {Buffer} data The information from the proc file.
- * @param {object} agent Newrelic agent instance.
- * @param {Function} callback Typical error first callback. Second parameter
+ * @param {Object} params params object
+ * @param {Buffer} params.data The information from the proc file.
+ * @param {Agent} params.agent Newrelic agent instance.
+ * @param {Function} params.callback Typical error first callback. Second parameter
  * is the boot id as a string.
  *
  * @returns {*}

package/lib/w3c/traceparent.js

@@ -90,7 +90,7 @@ class Traceparent {
    *
    * @link https://opentelemetry.io/docs/concepts/signals/traces/#span-context
    *
-   * @param {object} spanContext
+   * @param {object} spanContext OTEL span context
    *
    * @returns {Traceparent}
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newrelic",
-  "version": "13.3.2",
+  "version": "13.4.0",
   "author": "New Relic Node.js agent team <nodejs@newrelic.com>",
   "license": "Apache-2.0",
   "contributors": [
@@ -201,7 +201,7 @@
     "#test/assert": "./test/lib/custom-assertions/index.js"
   },
   "dependencies": {
-    "@apm-js-collab/tracing-hooks": "^0.1.0",
+    "@apm-js-collab/tracing-hooks": "^0.3.1",
     "@grpc/grpc-js": "^1.13.2",
     "@grpc/proto-loader": "^0.7.5",
     "@newrelic/security-agent": "^2.4.2",