newrelic 12.15.0 → 12.16.1

package/NEWS.md

@@ -1,3 +1,49 @@
+### v12.16.1 (2025-03-24)
+
+#### Features
+
+* Assign all attributes on internal spans to segment ([#3000](https://github.com/newrelic/node-newrelic/pull/3000)) ([5403018](https://github.com/newrelic/node-newrelic/commit/54030185ba5630099b76182a52c629276af4d93e))
+
+#### Bug fixes
+
+* Fixed `tracer.transactionNestProxy` to create a new transaction if there is no transaction or transaction is not active ([#3007](https://github.com/newrelic/node-newrelic/pull/3007)) ([ced9e22](https://github.com/newrelic/node-newrelic/commit/ced9e22a23ddeed860c1fd88f0afb10bb94343cb))
+
+#### Documentation
+
+* Updated compatibility report ([#2993](https://github.com/newrelic/node-newrelic/pull/2993)) ([cdfa042](https://github.com/newrelic/node-newrelic/commit/cdfa042325a7636e84a7b19a34874b20915dac63))
+
+#### Tests
+
+* Fixed handling require esm for >20.19.0+ ([#3002](https://github.com/newrelic/node-newrelic/pull/3002)) ([b808e00](https://github.com/newrelic/node-newrelic/commit/b808e00c399d3c924eeeb19f9c6b9fba4695a720))
+
+### v12.16.0 (2025-03-17)
+
+#### Features
+
+* Added support for response streaming Lambda functions ([#2981](https://github.com/newrelic/node-newrelic/pull/2981)) ([61dbbf9](https://github.com/newrelic/node-newrelic/commit/61dbbf9b4a6cf69f5378387fc9c17c31671e9da4))
+* Added AWS entity linking segment attributes for otel bridge ([#2978](https://github.com/newrelic/node-newrelic/pull/2978)) ([6bf1ccc](https://github.com/newrelic/node-newrelic/commit/6bf1ccc657a955b4064a7a3a473bf24948d4ff56))
+* Added error handling on transactions for otel spans ([#2985](https://github.com/newrelic/node-newrelic/pull/2985)) ([4e61e09](https://github.com/newrelic/node-newrelic/commit/4e61e0935394744345c39f6b581ee86e66d0f82c))
+
+#### Code refactoring
+
+* Updated span event generation to assign the appropriate `span.kind` based on the segment name ([#2976](https://github.com/newrelic/node-newrelic/pull/2976)) ([697b17e](https://github.com/newrelic/node-newrelic/commit/697b17e0553111aa494d08bc33eb7043cdfa8ca6))
+
+#### Documentation
+
+* Updated compatibility report ([#2988](https://github.com/newrelic/node-newrelic/pull/2988)) ([ed17a6d](https://github.com/newrelic/node-newrelic/commit/ed17a6df1152a8e54cb8c8570fec0015990a4247)
+
+#### Miscellaneous chores
+
+* Clarified supported next.js middleware versions in docs ([#2984](https://github.com/newrelic/node-newrelic/pull/2984)) ([15cb454](https://github.com/newrelic/node-newrelic/commit/15cb454f9cc38ccc22089d62aaeea54713159aa7))
+* Clarified system metrics sampler naming ([#2987](https://github.com/newrelic/node-newrelic/pull/2987)) ([8647d43](https://github.com/newrelic/node-newrelic/commit/8647d43f097d6d3d68a372824d9feb325604be96))
+* Refactored loops to be simpler ([#2990](https://github.com/newrelic/node-newrelic/pull/2990)) ([79fb8e9](https://github.com/newrelic/node-newrelic/commit/79fb8e90802954b617c1c00aecc866aa065aee12))
+* Removed unused transaction method ([#2986](https://github.com/newrelic/node-newrelic/pull/2986)) ([cb4e2f7](https://github.com/newrelic/node-newrelic/commit/cb4e2f7a8b84adb6d744a2083b083c92e306fbd5))
+* Reverted restriction in NestJS versioned tests ([#2979](https://github.com/newrelic/node-newrelic/pull/2979)) ([ffddcab](https://github.com/newrelic/node-newrelic/commit/ffddcab6d77bfc10c0df9cbfa724bc1c8f5fb251))
+
+#### Tests
+
+* Fixed fastify assertions around span kind while running security agent ([#2983](https://github.com/newrelic/node-newrelic/pull/2983)) ([c641645](https://github.com/newrelic/node-newrelic/commit/c6416451f1fa6126b7dfd59f6b9267f9d2188ad0))
+
 ### v12.15.0 (2025-03-03)
 
 #### Features

package/README.md

@@ -31,7 +31,7 @@ To use New Relic's Node.js agent entails these three steps, which are described
 
 3. Now, add your New Relic license key and application/service name to that file:
 
-```js
+    ```js
     /* File: newrelic.js */
     'use strict'
     /**
@@ -45,30 +45,29 @@ To use New Relic's Node.js agent entails these three steps, which are described
       license_key: 'your new relic license key',
       /* ... rest of configuration .. */
     }
-```
+    ```
 
 4. Finally, run your program with the `newrelic` module loaded first by using node's `-r/--require` flag.
 
-```
- $ node -r newrelic your-program.js
-```
+    ```sh
+    $ node -r newrelic your-program.js
+    ```
 
-If you cannot control how your program is run, you can load the `newrelic` module _before any other module_ in your program.
+    If you cannot control how your program is run, you can load the `newrelic` module _before any other module_ in your program.
 
-```js
+    ```js
     const newrelic = require('newrelic')
 
     /* ... the rest of your program ... */
-```
+    ```
 
 ## Next.js instrumentation
 **Note**: The minimum supported Next.js version is [12.0.9](https://github.com/vercel/next.js/releases/tag/v12.0.9).  If you are using Next.js middleware the minimum supported version is [12.2.0](https://github.com/vercel/next.js/releases/tag/v12.2.0).
 
-The New Relic Node.js agent provides instrumentation for Next.js  The instrumentation provides telemetry for server-side rendering via [getServerSideProps](https://nextjs.org/docs/basic-features/data-fetching/get-server-side-props), [middleware](https://nextjs.org/docs/middleware), and New Relic transaction naming for both page and server requests. It does not provide any instrumentation for actions occurring during build or in client-side code.  If you want telemetry data on actions occurring on the client (browser), you can [inject the browser agent](./documentation/nextjs/faqs/browser-agent.md).
+The New Relic Node.js agent provides instrumentation for Next.js  The instrumentation provides telemetry for server-side rendering via [`getServerSideProps`](https://nextjs.org/docs/basic-features/data-fetching/get-server-side-props), [middleware](https://nextjs.org/docs/middleware) (limited to Next.js versions [12.2.0](https://github.com/vercel/next.js/releases/tag/v12.2.0) - [13.4.12](https://github.com/vercel/next.js/releases/tag/v13.4.12)), and New Relic transaction naming for both page and server requests. It does not provide any instrumentation for actions occurring during build or in client-side code.  If you want telemetry data on actions occurring on the client (browser), you can [inject the browser agent](./documentation/nextjs/faqs/browser-agent.md).
 
 Here are documents for more in-depth explanations about [transaction naming](./documentation/nextjs/transactions.md), and [segments/spans](./documentation/nextjs/segments-and-spans.md).
 
-
 ### Setup
 Typically you are running a Next.js app with the `next` cli and you must load the agent via `NODE_OPTIONS`:
 
@@ -102,15 +101,15 @@ The New Relic Node.js agent includes ***_experimental_*** support for ES Modules
 
  1. If you rely on a configuration file to run the agent, you must rename the file from `newrelic.js` to `newrelic.cjs` so it can be properly loaded.  All the contents of the configuration file will behave the same once you rename. See [CommonJS modules in ESM](https://nodejs.org/api/modules.html#enabling) for more details.
 
-```sh
-$ mv newrelic.js newrelic.cjs
-```
+    ```sh
+    $ mv newrelic.js newrelic.cjs
+    ```
 
  2. To use the newrelic ESM loader, start your program with node and use the `--experimental-loader` flag and a path to the loader file, like this:
 
-```sh
-$ node --experimental-loader newrelic/esm-loader.mjs -r newrelic your-program.js
-```
+    ```sh
+    $ node --experimental-loader newrelic/esm-loader.mjs -r newrelic your-program.js
+    ```
 
 **Note**: Unlike the CommonJS methods listed above, there are no alternatives to running the agent without the `--experimental-loader` flag.
 
@@ -122,11 +121,11 @@ The agent supports adding your own custom instrumentation to ES module applicati
 import newrelic from 'newrelic'
 newrelic.instrument({ moduleName: 'parse-json', isEsm: true }, function wrap(shim, parseJson, moduleName) {
   shim.wrap(parseJson.default, function wrapParseJson(shim, orig) {
-      return function wrappedParseJson() {
-          const result = orig.apply(this, arguments)
-          result.instrumented = true
-          return true
-      }
+    return function wrappedParseJson() {
+      const result = orig.apply(this, arguments)
+      result.instrumented = true
+      return true
+    }
   })
 })
 ```
@@ -151,11 +150,11 @@ For more information on getting started, [check the Node.js docs](https://docs.n
 
 There are modules that can be installed and configured to accompany the Node.js agent:
 
- * [@newrelic/apollo-server-plugin](https://github.com/newrelic/newrelic-node-apollo-server-plugin): New Relic's official Apollo Server plugin for use with the Node.js agent.
+ * [`@newrelic/apollo-server-plugin`](https://github.com/newrelic/newrelic-node-apollo-server-plugin): New Relic's official Apollo Server plugin for use with the Node.js agent.
 
 There are modules included within the Node.js agent to add more instrumentation for 3rd party modules:
 
- * [@newrelic/native-metrics](https://github.com/newrelic/node-native-metrics): Provides hooks into the native v8 layer of Node.js to provide metrics to the Node.js agent.
+ * [`@newrelic/native-metrics`](https://github.com/newrelic/node-native-metrics): Provides hooks into the native v8 layer of Node.js to provide metrics to the Node.js agent.
 
 ## Usage
 
@@ -164,10 +163,10 @@ There are modules included within the Node.js agent to add more instrumentation
 The `newrelic` module returns an object with the Node.js agent's API methods attached.
 
 ```js
-    const newrelic = require('newrelic')
+const newrelic = require('newrelic')
 
-    /* ... */
-    newrelic.addCustomAttribute('some-attribute', 'some-value')
+/* ... */
+newrelic.addCustomAttribute('some-attribute', 'some-value')
 ```
 
 You can read more about using the API over on the [New Relic documentation](https://docs.newrelic.com/docs/agents/nodejs-agent/api-guides/guide-using-nodejs-agent-api) site.
@@ -182,12 +181,16 @@ These are the steps to work on core agent features, with more detail below:
 
 1. [Fork](https://github.com/newrelic/node-newrelic/fork) and clone this GitHub repository:
 
+    ```sh
     $ git clone git@github.com:your-user-name/node-newrelic.git
     $ cd node-newrelic
+    ```
 
 2. Install the project's dependencies:
 
+    ```sh
     $ npm install
+    ```
 
 Then you're all set to start programming.
 
@@ -199,11 +202,13 @@ Then you're all set to start programming.
 
 Available test suites include:
 
-    $ npm run unit
-    $ npm run integration
-    $ npm run versioned
-    $ npm run lint
-    $ npm run smoke
+  ```sh
+  $ npm run unit
+  $ npm run integration
+  $ npm run versioned
+  $ npm run lint
+  $ npm run smoke
+  ```
 
 ## Further Reading
 

package/api.js

@@ -992,6 +992,7 @@ API.prototype.startWebTransaction = function startWebTransaction(url, handle) {
       transaction: tx,
       parent
     })
+    tx.baseSegment.spanKind = 'server'
     const newContext = context.enterSegment({ transaction: tx, segment: tx.baseSegment })
     tx.baseSegment.start()
 
@@ -1101,6 +1102,7 @@ function startBackgroundTransaction(name, group, handle) {
       parent
     })
     const newContext = context.enterSegment({ transaction: tx, segment: tx.baseSegment })
+    tx.baseSegment.spanKind = 'server'
     tx.baseSegment.partialName = group
     tx.baseSegment.start()
 

package/lib/agent.js

@@ -21,7 +21,7 @@ const MetricNormalizer = require('./metrics/normalizer')
 const MetricAggregator = require('./metrics/metric-aggregator')
 const NAMES = require('./metrics/names')
 const QueryTraceAggregator = require('./db/query-trace-aggregator')
-const sampler = require('./sampler')
+const systemMetricsSampler = require('./system-metrics-sampler')
 const TransactionTraceAggregator = require('./transaction/trace/aggregator')
 const TransactionEventAggregator = require('./transaction/transaction-event-aggregator')
 const Tracer = require('./transaction/tracer')
@@ -334,7 +334,7 @@ Agent.prototype.start = function start(callback) {
     return process.nextTick(callback)
   }
 
-  sampler.start(agent)
+  systemMetricsSampler.start(agent)
 
   if (this.config.serverless_mode.enabled) {
     return this._serverlessModeStart(callback)
@@ -349,7 +349,7 @@ Agent.prototype.start = function start(callback) {
     this.healthReporter.setStatus(HealthReporter.STATUS_LICENSE_KEY_MISSING)
 
     this.setState('errored')
-    sampler.stop()
+    systemMetricsSampler.stop()
     return process.nextTick(function onNextTick() {
       agent.healthReporter.stop(() => {
         callback(new Error('Not starting without license key!'))
@@ -362,7 +362,7 @@ Agent.prototype.start = function start(callback) {
     if (error || response.shouldShutdownRun()) {
       agent.healthReporter.setStatus(HealthReporter.STATUS_CONNECT_ERROR)
       agent.setState('errored')
-      sampler.stop()
+      systemMetricsSampler.stop()
       callback(error || new Error('Failed to connect to collector'), response && response.payload)
       return
     }
@@ -482,7 +482,7 @@ Agent.prototype.stop = function stop(callback) {
 
   this.harvester.stop()
 
-  sampler.stop()
+  systemMetricsSampler.stop()
 
   this.healthReporter.setStatus(HealthReporter.STATUS_AGENT_SHUTDOWN)
   this.healthReporter.stop(() => {

package/lib/context-manager/context.js

@@ -29,7 +29,7 @@ module.exports = class Context {
    * @returns {Context} a newly constructed context
    */
   enterSegment({ segment, transaction = this._transaction }) {
-    return new this.constructor(transaction, segment, this._otelCtx)
+    return new this.constructor(transaction, segment)
   }
 
   /**

package/lib/errors/error-collector.js

@@ -215,8 +215,9 @@ class ErrorCollector {
    * @param {?Transaction}  transaction  Transaction associated with the error.
    * @param {Error}  error  The error to be traced.
    * @param {?object}  customAttributes  Custom attributes associated with the request (optional).
+   * @param {object} segment The segment associated with the error (optional). Only used in otel bridge.
    */
-  add(transaction, error, customAttributes) {
+  add(transaction, error, customAttributes, segment) {
     if (!error) {
       return
     }
@@ -236,7 +237,7 @@ class ErrorCollector {
     const exception = new Exception({ error, timestamp, customAttributes })
 
     if (transaction) {
-      transaction.addException(exception)
+      transaction.addException(exception, segment)
     } else {
       this.collect(transaction, exception)
     }

package/lib/instrumentation/kafkajs/consumer.js

@@ -42,7 +42,7 @@ function wrapConsumer(shim, orig) {
       consumer,
       'run',
       new MessageSubscribeSpec({
-        name: `${SEGMENT_PREFIX}#run`,
+        name: `${SEGMENT_PREFIX}run`,
         destinationType: shim.TOPIC,
         promise: true,
         consumer: shim.FIRST,

package/lib/otel/constants.js

@@ -61,6 +61,14 @@ module.exports = {
    */
   ATTR_DB_SYSTEM: 'db.system',
 
+  /**
+   * The cloud provider of the invoked function.
+   *
+   * @example aws
+   * @see https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/specification/trace/semantic_conventions/faas.md#outgoing-invocations
+   */
+  ATTR_FAAS_INVOKED_PROVIDER: 'faas.invoked_provider',
+
   /**
    * The full resource URL.
    *
@@ -182,7 +190,8 @@ module.exports = {
    * Target messaging system name.
    *
    * @example kafka
-   * @see https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/
+   * @example aws_sqs
+   * @see https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/#messaging-attributes
    */
   ATTR_MESSAGING_SYSTEM: 'messaging.system',
 
@@ -233,7 +242,7 @@ module.exports = {
   ATTR_NET_HOST_NAME: 'net.host.name',
 
   /**
-   * Poort of the local HTTP server that received the request.
+   * Port of the local HTTP server that received the request.
    *
    * @example 80
    */
@@ -322,11 +331,35 @@ module.exports = {
     VERTICA: 'vertica',
   },
 
+  /**
+   * The exception message
+   */
+  EXCEPTION_MESSAGE: 'exception.message',
+
+  /**
+   * The exception stacktrace
+   */
+  EXCEPTION_STACKTRACE: 'exception.stacktrace',
+
+  /**
+   * The exception type
+   */
+  EXCEPTION_TYPE: 'exception.type',
+
   /**
    * Kinds of messaging system destinations.
    */
   MESSAGING_SYSTEM_KIND_VALUES: {
     QUEUE: 'queue',
     TOPIC: 'topic'
+  },
+
+  /**
+   * An enumeration of status codes
+   */
+  SPAN_STATUS_CODE: {
+    UNSET: 0,
+    OK: 1,
+    ERROR: 2
   }
 }

package/lib/otel/segments/internal.js

@@ -4,7 +4,7 @@
  */
 
 'use strict'
-const customRecorder = require('../../metrics/recorders/custom')
+const genericRecorder = require('../../metrics/recorders/generic')
 
 module.exports = function createInternalSegment(agent, otelSpan) {
   const context = agent.tracer.getContext()
@@ -13,7 +13,7 @@ module.exports = function createInternalSegment(agent, otelSpan) {
     id: otelSpan?.spanContext()?.spanId,
     name,
     parent: context.segment,
-    recorder: customRecorder,
+    recorder: genericRecorder,
     transaction: context.transaction
   })
   return { segment, transaction: context.transaction }

package/lib/otel/span-processor.js

@@ -16,6 +16,7 @@ const {
   ATTR_DB_NAME,
   ATTR_DB_STATEMENT,
   ATTR_DB_SYSTEM,
+  ATTR_FAAS_INVOKED_PROVIDER,
   ATTR_FULL_URL,
   ATTR_GRPC_STATUS_CODE,
   ATTR_HTTP_METHOD,
@@ -34,9 +35,15 @@ const {
   ATTR_NET_PEER_NAME,
   ATTR_NET_PEER_PORT,
   ATTR_RPC_SYSTEM,
+  ATTR_RPC_SERVICE,
   ATTR_SERVER_ADDRESS,
   ATTR_SERVER_PORT,
   ATTR_URL_QUERY,
+  DB_SYSTEM_VALUES,
+  EXCEPTION_MESSAGE,
+  EXCEPTION_STACKTRACE,
+  EXCEPTION_TYPE,
+  SPAN_STATUS_CODE
 } = require('./constants')
 const { DESTINATIONS } = require('../config/attribute-filter')
 
@@ -62,19 +69,33 @@ module.exports = class NrSpanProcessor {
   }
 
   /**
-   * Update the segment duration from span and reconcile
-   * any attributes that were added after the start
+   * Update the segment duration from span, handle errors and
+   * reconcile any attributes that were added after the start
    * @param {object} span otel span getting updated
    */
   onEnd(span) {
     if (span[otelSynthesis] && span[otelSynthesis].segment) {
       const { segment, transaction } = span[otelSynthesis]
       this.updateDuration(segment, span)
+      this.handleError({ segment, transaction, span })
       this.reconcileAttributes({ segment, span, transaction })
       delete span[otelSynthesis]
     }
   }
 
+  handleError({ segment, transaction, span }) {
+    if (span?.status?.code === SPAN_STATUS_CODE.ERROR) {
+      const errorEvents = span.events.filter((event) => event.name === 'exception')
+      errorEvents.forEach((err) => {
+        const msg = err.attributes[EXCEPTION_MESSAGE] || err.attributes[EXCEPTION_TYPE] || `Error from ${segment.name}`
+        const stack = err.attributes[EXCEPTION_STACKTRACE]
+        const error = new Error(msg)
+        error.stack = stack
+        this.agent.errors.add(transaction, error, null, segment)
+      })
+    }
+  }
+
   updateDuration(segment, span) {
     segment.touch()
     const duration = hrTimeToMilliseconds(span.duration)
@@ -92,11 +113,15 @@ module.exports = class NrSpanProcessor {
       this.reconcileProducerAttributes({ segment, span })
     } else if (span.kind === SpanKind.CLIENT && (span.attributes[ATTR_HTTP_METHOD] || span.attributes[ATTR_HTTP_REQUEST_METHOD])) {
       this.reconcileHttpExternalAttributes({ segment, span })
+    } else {
+      this.#reconciler.reconcile({ segment, otelSpan: span })
     }
+
+    this.addAWSLinkingAttributes({ segment, span })
   }
 
   reconcileHttpExternalAttributes({ segment, span }) {
-    const noOpMapper = () => {}
+    const noOpMapper = () => { }
     const statusCode = (value) => segment.addSpanAttribute('http.statusCode', value)
     const statusText = (value) => segment.addSpanAttribute('http.statusText', value)
     const mapper = {
@@ -147,6 +172,7 @@ module.exports = class NrSpanProcessor {
       [ATTR_MESSAGING_DESTINATION_NAME]: queueNameMapper,
       [ATTR_MESSAGING_DESTINATION]: queueNameMapper
     }
+
     this.#reconciler.reconcile({ segment: baseSegment, otelSpan: span, mapper })
 
     transaction.end()
@@ -240,7 +266,7 @@ module.exports = class NrSpanProcessor {
          * to be skipped because it will be the raw value.
          */
       },
-      [ATTR_DB_STATEMENT]: () => {}
+      [ATTR_DB_STATEMENT]: () => { }
     }
     this.#reconciler.reconcile({ segment, otelSpan: span, mapper })
   }
@@ -252,6 +278,44 @@ module.exports = class NrSpanProcessor {
       [ATTR_MESSAGING_MESSAGE_CONVERSATION_ID]: (value) => segment.addAttribute('correlation_id', value),
       [ATTR_MESSAGING_RABBITMQ_DESTINATION_ROUTING_KEY]: (value) => segment.addAttribute('routing_key', value)
     }
+
     this.#reconciler.reconcile({ segment, otelSpan: span, mapper })
   }
+
+  addAWSLinkingAttributes({ segment, span }) {
+    const accountId = this.agent?.config?.cloud?.aws?.account_id
+    const region = span.attributes['faas.invoked_region'] ?? span.attributes['aws.region'] // faas.invoked_region is for Lambda and takes precedence
+
+    // DynamoDB
+    if (span.attributes[ATTR_DB_SYSTEM] === DB_SYSTEM_VALUES.DYNAMODB ||
+      span.attributes[ATTR_RPC_SERVICE]?.toLowerCase() === 'dynamodb'
+    ) {
+      const collection = span.attributes?.['aws.dynamodb.table_names'][0]
+      if (region && accountId && collection) {
+        segment.addAttribute('cloud.resource_id', `arn:aws:dynamodb:${region}:${accountId}:table/${collection}`)
+      }
+    }
+
+    // Lambda
+    if (span.attributes[ATTR_FAAS_INVOKED_PROVIDER] === 'aws') {
+      const functionName = span.attributes['faas.invoked_name']
+      if (region && accountId && functionName) {
+        segment.addAttribute('cloud.platform', 'aws_lambda')
+        segment.addAttribute('cloud.resource_id', `arn:aws:lambda:${region}:${accountId}:function:${functionName}`)
+      }
+    }
+
+    // SQS
+    if (span.attributes[ATTR_RPC_SERVICE]?.toLowerCase() === 'sqs') {
+      if (accountId) {
+        segment.addAttribute('cloud.account.id', accountId)
+      }
+      if (region) {
+        segment.addAttribute('cloud.region', region)
+      }
+      const messagingDestination = span.attributes[ATTR_MESSAGING_DESTINATION]
+      segment.addAttribute('messaging.destination.name', messagingDestination)
+      segment.addAttribute('messaging.system', 'aws_sqs')
+    }
+  }
 }

package/lib/serverless/aws-lambda.js

@@ -24,6 +24,7 @@ const EVENT_SOURCE_TYPE_KEY = `${EVENT_SOURCE_PREFIX}.eventType`
 const NAMES = require('../metrics/names')
 
 const EVENT_SOURCE_INFO = require('./event-sources')
+const HANDLER_STREAMING = Symbol.for('aws.lambda.runtime.handler.streaming')
 
 // A function with no references used to stub out closures
 function cleanClosure() {}
@@ -35,7 +36,7 @@ let transactionEnders = []
 // the invocation transaction.
 let uncaughtException = null
 
-// Tracking the first time patchLambdaHandler is called for one off functionality
+// Tracking the first time patchLambdaHandler is called for one-off functionality
 let patchCalled = false
 let coldStartRecorded = false
 
@@ -105,6 +106,45 @@ class AwsLambda {
     })
   }
 
+  /**
+   * Response-streaming handlers are identified by symbol properties on the function.
+   * We propagate any symbols if they're present, so that the handler keeps its signatue for any AWS features that rely on symbols
+   * @param handler
+   * @param nrHandler
+   */
+  propagateSymbols(handler, nrHandler) {
+    for (const symbol of Object.getOwnPropertySymbols(handler)) {
+      logger.trace(`Setting symbol ${symbol.toString()} on handler`)
+      nrHandler[symbol] = handler[symbol]
+    }
+  }
+
+  createSegment({ event, context, transaction, recorder }) {
+    const shim = this.shim
+    const functionName = context.functionName
+    const group = NAMES.FUNCTION.PREFIX
+    const transactionName = group + functionName
+
+    const activeSegment = shim.tracer.getSegment()
+
+    transaction.setPartialName(transactionName)
+    const txnEnder = endTransaction.bind(null, transaction, transactionEnders.length)
+
+    transactionEnders.push(txnEnder)
+    const segment = shim.createSegment(functionName, recorder, activeSegment)
+    transaction.baseSegment = segment
+    const awsAttributes = this._getAwsAgentAttributes(event, context)
+    transaction.trace.attributes.addAttributes(ATTR_DEST.TRANS_COMMON, awsAttributes)
+
+    shim.agent.setLambdaArn(context.invokedFunctionArn)
+
+    shim.agent.setLambdaFunctionVersion(context.functionVersion)
+    segment.addSpanAttributes(awsAttributes)
+
+    segment.start()
+    return { segment, txnEnder }
+  }
+
   patchLambdaHandler(handler) {
     const awsLambda = this
     const shim = this.shim
@@ -114,6 +154,11 @@ class AwsLambda {
       return handler
     }
 
+    const isStreamHandler = handler[HANDLER_STREAMING] === 'response'
+    if (isStreamHandler) {
+      this.agent.recordSupportability('Nodejs/Serverless/Lambda/ResponseStreaming')
+    }
+
     if (!patchCalled) {
       // Only wrap emit on process the first time patch is called.
       patchCalled = true
@@ -122,52 +167,87 @@ class AwsLambda {
       this.wrapFatal()
     }
 
-    return shim.bindCreateTransaction(wrappedHandler, new specs.TransactionSpec({ type: shim.BG }))
+    const wrapper = isStreamHandler ? wrappedStreamHandler : wrappedHandler
+    const nrHandler = shim.bindCreateTransaction(wrapper, new specs.TransactionSpec({ type: shim.BG }))
+    awsLambda.propagateSymbols(handler, nrHandler)
+
+    return nrHandler
+
+    /**
+     * Wraps a response streaming lambda handler.
+     *
+     * Creates and applies segment based on function name, assigns attributes to transaction trace,
+     * listen when stream errors(log error), ends(end transaction)
+     *
+     * **Note**: AWS doesn't support response streaming with API gateway invoked lambdas.
+     * This means we do not handle that as it would require intercepting the stream to parse
+     * the response code and headers.
+     */
+    function wrappedStreamHandler() {
+      const transaction = shim.tracer.getTransaction()
+      if (!transaction) {
+        logger.trace('No active transaction, not wrapping streaming handler')
+        return handler.apply(this, arguments)
+      }
 
-    function wrappedHandler() {
       const args = shim.argsToArray.apply(shim, arguments)
-
       const event = args[0]
-      const context = args[1]
+      const context = args[2]
+      logger.trace('In stream handler, lambda function name', context?.functionName)
+      const { segment, txnEnder } = awsLambda.createSegment({ context, event, transaction, recorder: recordBackground })
+      args[1] = awsLambda.wrapStreamAndCaptureError(
+        transaction,
+        txnEnder,
+        args[1]
+      )
 
-      const functionName = context.functionName
-      const group = NAMES.FUNCTION.PREFIX
-      const transactionName = group + functionName
+      let res
+      try {
+        res = shim.applySegment(handler, segment, false, this, args)
+      } catch (err) {
+        uncaughtException = err
+        txnEnder()
+        throw err
+      }
+
+      return res
+    }
 
+    /**
+     * Wraps a non response streaming lambda handler.
+     *
+     * Creates and applies segment based on function name, assigns attributes to transaction trace,
+     * adds handlers if api gateway to wrap request/response
+     * wraps the callback(if present), wraps the context `done`, `succeed`, `fail methods`, intercepts promise
+     * and properly ends transaction
+     */
+    function wrappedHandler() {
       const transaction = shim.tracer.getTransaction()
       if (!transaction) {
+        logger.trace('No active transaction, not wrapping handler')
         return handler.apply(this, arguments)
       }
-      const activeSegment = shim.tracer.getSegment()
-
-      transaction.setPartialName(transactionName)
+      const args = shim.argsToArray.apply(shim, arguments)
 
+      const event = args[0]
+      const context = args[1]
+      logger.trace('Lambda function name', context?.functionName)
       const isApiGatewayLambdaProxy = apiGateway.isLambdaProxyEvent(event)
+      logger.trace('Is this Lambda event an API Gateway or ALB web proxy?', isApiGatewayLambdaProxy)
+      logger.trace('Lambda event keys', Object.keys(event))
       const segmentRecorder = isApiGatewayLambdaProxy ? recordWeb : recordBackground
-      const segment = shim.createSegment(functionName, segmentRecorder, activeSegment)
-      transaction.baseSegment = segment
+      const { segment, txnEnder } = awsLambda.createSegment({ context, event, transaction, recorder: segmentRecorder })
+
       // resultProcessor is used to execute additional logic based on the
       // payload supplied to the callback.
       let resultProcessor
 
-      logger.trace('Is this Lambda event an API Gateway or ALB web proxy?', isApiGatewayLambdaProxy)
-      logger.trace('Lambda event keys', Object.keys(event))
-
       if (isApiGatewayLambdaProxy) {
         const webRequest = new apiGateway.LambdaProxyWebRequest(event)
         setWebRequest(shim, transaction, webRequest)
         resultProcessor = getApiGatewayLambdaProxyResultProcessor(transaction)
       }
-
       const cbIndex = args.length - 1
-
-      // Add transaction ending closure to the list of functions to be called on
-      // beforeExit (i.e. in the case that context.{done,fail,succeed} or callback
-      // were not called).
-      const txnEnder = endTransaction.bind(null, transaction, transactionEnders.length)
-
-      transactionEnders.push(txnEnder)
-
       args[cbIndex] = awsLambda.wrapCallbackAndCaptureError(
         transaction,
         txnEnder,
@@ -186,16 +266,6 @@ class AwsLambda {
         }
       })
 
-      const awsAttributes = awsLambda._getAwsAgentAttributes(event, context)
-      transaction.trace.attributes.addAttributes(ATTR_DEST.TRANS_COMMON, awsAttributes)
-
-      shim.agent.setLambdaArn(context.invokedFunctionArn)
-
-      shim.agent.setLambdaFunctionVersion(context.functionVersion)
-      segment.addSpanAttributes(awsAttributes)
-
-      segment.start()
-
       let res
       try {
         res = shim.applySegment(handler, segment, false, this, args)
@@ -251,6 +321,18 @@ class AwsLambda {
     }
   }
 
+  wrapStreamAndCaptureError(transaction, txnEnder, stream) {
+    const shim = this.shim
+    stream.on('error', (error) => {
+      shim.agent.errors.add(transaction, error)
+    })
+
+    stream.on('close', () => {
+      txnEnder()
+    })
+    return stream
+  }
+
   _getAwsAgentAttributes(event, context) {
     const attributes = {
       'aws.lambda.arn': context.invokedFunctionArn,
@@ -372,7 +454,7 @@ function lowercaseObjectKeys(original) {
 }
 
 function endTransaction(transaction, enderIndex) {
-  if (transactionEnders[enderIndex] === cleanClosure) {
+  if (transactionEnders.length === 0 || transactionEnders[enderIndex] === cleanClosure) {
     // In the case where we have already been called, we return early. There may be a
     // case where this is called more than once, given the lambda is left in a dirty
     // state after thread suspension (e.g. timeouts)
@@ -411,7 +493,7 @@ function setWebResponse(transaction, response) {
 
     // We are adding http.statusCode to base segment as
     // we found in testing async invoked lambdas, the
-    // active segement is not available at this point.
+    // active segment is not available at this point.
     const segment = transaction.baseSegment
 
     segment.addSpanAttribute('http.statusCode', responseCode)

package/lib/spans/helpers.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const HTTP_LIBRARY = 'http'
+const CATEGORIES = {
+  HTTP: 'http',
+  DATASTORE: 'datastore',
+  GENERIC: 'generic'
+}
+
+const SPAN_KIND = {
+  CONSUMER: 'consumer',
+  CLIENT: 'client',
+  INTERNAL: 'internal',
+  PRODUCER: 'producer',
+  SERVER: 'server'
+}
+
+const REGEXS = {
+  CONSUMER: /^(?:Truncated\/)?OtherTransaction\/Message\//,
+  CLIENT: {
+    EXTERNAL: /^(?:Truncated\/)?External\//,
+    DATASTORE: /^(?:Truncated\/)?Datastore\//,
+  },
+  PRODUCER: /^(?:Truncated\/)?MessageBroker\//,
+  SERVER: /^(?:Truncated\/)?(WebTransaction)\//
+}
+
+/**
+ * Assigns the appropriate span kind based on the segment name.
+ * Does not handle client kind as this is done in the `HttpSpanEvent` and `DatastoreSpanEvent`
+ * Our agent has conventions for naming all types of segments.
+ * The only place this convention does not exist is within the `api.startWebTransaction`
+ * and `api.startBackgroundTransaction`. For those, we have assigned a `spanKind` property
+ * on the segment.  We default to `internal` if it cannot match a regex.
+ *
+ * @param {object} params to function
+ * @param {TraceSegment} params.segment segment that is creating span
+ * @param {object} params.span span to add `intrinsics['span.kind']`
+ */
+function addSpanKind({ segment, span }) {
+  const intrinsics = span.getIntrinsicAttributes()
+  if (!intrinsics['span.kind']) {
+    let spanKind
+    if (segment.spanKind) {
+      spanKind = segment.spanKind
+    } else if (REGEXS.CONSUMER.test(segment.name)) {
+      spanKind = SPAN_KIND.CONSUMER
+    } else if (REGEXS.PRODUCER.test(segment.name)) {
+      spanKind = SPAN_KIND.PRODUCER
+    } else if (REGEXS.SERVER.test(segment.name)) {
+      spanKind = SPAN_KIND.SERVER
+    } else {
+      spanKind = SPAN_KIND.INTERNAL
+    }
+
+    span.addIntrinsicAttribute('span.kind', spanKind)
+  }
+}
+
+module.exports = {
+  HTTP_LIBRARY,
+  CATEGORIES,
+  SPAN_KIND,
+  REGEXS,
+  addSpanKind
+}

package/lib/spans/span-event.js

@@ -9,18 +9,7 @@ const Config = require('../config')
 const { truncate } = require('../util/byte-limit')
 
 const { DESTINATIONS } = require('../config/attribute-filter')
-
-const HTTP_LIBRARY = 'http'
-const CLIENT_KIND = 'client'
-const CATEGORIES = {
-  HTTP: 'http',
-  DATASTORE: 'datastore',
-  GENERIC: 'generic'
-}
-
-const EXTERNAL_REGEX = /^(?:Truncated\/)?External\//
-const DATASTORE_REGEX = /^(?:Truncated\/)?Datastore\//
-
+const { addSpanKind, HTTP_LIBRARY, REGEXS, SPAN_KIND, CATEGORIES } = require('./helpers')
 const EMPTY_USER_ATTRS = Object.freeze(Object.create(null))
 const SERVER_ADDRESS = 'server.address'
 
@@ -74,6 +63,14 @@ class SpanEvent {
     }
   }
 
+  getIntrinsicAttributes() {
+    return this.intrinsics
+  }
+
+  addIntrinsicAttribute(key, value) {
+    this.intrinsics[key] = value
+  }
+
   static get CATEGORIES() {
     return CATEGORIES
   }
@@ -153,6 +150,7 @@ class SpanEvent {
     span.intrinsics.timestamp = segment.timer.start
     span.intrinsics.duration = segment.timer.getDurationInMillis() / 1000
 
+    addSpanKind({ segment, span })
     return span
   }
 
@@ -193,7 +191,7 @@ class HttpSpanEvent extends SpanEvent {
 
     this.intrinsics.category = CATEGORIES.HTTP
     this.intrinsics.component = attributes.library || HTTP_LIBRARY
-    this.intrinsics['span.kind'] = CLIENT_KIND
+    this.intrinsics['span.kind'] = SPAN_KIND.CLIENT
 
     if (attributes.library) {
       attributes.library = null
@@ -217,7 +215,7 @@ class HttpSpanEvent extends SpanEvent {
   }
 
   static testSegment(segment) {
-    return EXTERNAL_REGEX.test(segment.name)
+    return REGEXS.CLIENT.EXTERNAL.test(segment.name)
   }
 }
 
@@ -232,7 +230,7 @@ class DatastoreSpanEvent extends SpanEvent {
     super(attributes, customAttributes)
 
     this.intrinsics.category = CATEGORIES.DATASTORE
-    this.intrinsics['span.kind'] = CLIENT_KIND
+    this.intrinsics['span.kind'] = SPAN_KIND.CLIENT
 
     if (attributes.product) {
       this.intrinsics.component = attributes.product
@@ -279,7 +277,7 @@ class DatastoreSpanEvent extends SpanEvent {
   }
 
   static testSegment(segment) {
-    return DATASTORE_REGEX.test(segment.name)
+    return REGEXS.CLIENT.DATASTORE.test(segment.name)
   }
 }
 

package/lib/spans/streaming-span-event.js

@@ -10,17 +10,7 @@ const { truncate } = require('../util/byte-limit')
 const Config = require('../config')
 
 const { DESTINATIONS } = require('../config/attribute-filter')
-
-const HTTP_LIBRARY = 'http'
-const CLIENT_KIND = 'client'
-const CATEGORIES = {
-  HTTP: 'http',
-  DATASTORE: 'datastore',
-  GENERIC: 'generic'
-}
-
-const EXTERNAL_REGEX = /^(?:Truncated\/)?External\//
-const DATASTORE_REGEX = /^(?:Truncated\/)?Datastore\//
+const { addSpanKind, HTTP_LIBRARY, REGEXS, SPAN_KIND, CATEGORIES } = require('./helpers')
 
 /**
  * Specialized span event class for use with infinite streaming.
@@ -59,7 +49,7 @@ class StreamingSpanEvent {
   }
 
   /**
-   * Add a key/value pair to the Span's instrinisics collection.
+   * Add a key/value pair to the Span's intrinsics collection.
    *
    * @param {string} key Name of the attribute to be stored.
    * @param {string|boolean|number} value Value of the attribute to be stored.
@@ -68,6 +58,10 @@ class StreamingSpanEvent {
     this._intrinsicAttributes.addAttribute(key, value)
   }
 
+  getIntrinsicAttributes() {
+    return this._intrinsicAttributes
+  }
+
   /**
    * Add a key/value pair to the Span's custom/user attributes collection.
    *
@@ -169,6 +163,7 @@ class StreamingSpanEvent {
     // Timestamp in milliseconds, duration in seconds. Yay consistency!
     span.addIntrinsicAttribute('timestamp', segment.timer.start)
     span.addIntrinsicAttribute('duration', segment.timer.getDurationInMillis() / 1000)
+    addSpanKind({ segment, span })
 
     return span
   }
@@ -196,7 +191,7 @@ class StreamingHttpSpanEvent extends StreamingSpanEvent {
 
     this.addIntrinsicAttribute('category', CATEGORIES.HTTP)
     this.addIntrinsicAttribute('component', library || HTTP_LIBRARY)
-    this.addIntrinsicAttribute('span.kind', CLIENT_KIND)
+    this.addIntrinsicAttribute('span.kind', SPAN_KIND.CLIENT)
 
     if (url) {
       this.addAgentAttribute('http.url', url)
@@ -213,7 +208,7 @@ class StreamingHttpSpanEvent extends StreamingSpanEvent {
   }
 
   static isHttpSegment(segment) {
-    return EXTERNAL_REGEX.test(segment.name)
+    return REGEXS.CLIENT.EXTERNAL.test(segment.name)
   }
 }
 
@@ -248,7 +243,7 @@ class StreamingDatastoreSpanEvent extends StreamingSpanEvent {
     super(traceId, agentAttrs, customAttributes)
 
     this.addIntrinsicAttribute('category', CATEGORIES.DATASTORE)
-    this.addIntrinsicAttribute('span.kind', CLIENT_KIND)
+    this.addIntrinsicAttribute('span.kind', SPAN_KIND.CLIENT)
 
     if (product) {
       this.addIntrinsicAttribute('component', product)
@@ -288,7 +283,7 @@ class StreamingDatastoreSpanEvent extends StreamingSpanEvent {
   /* eslint-enable camelcase */
 
   static isDatastoreSegment(segment) {
-    return DATASTORE_REGEX.test(segment.name)
+    return REGEXS.CLIENT.DATASTORE.test(segment.name)
   }
 }
 

package/lib/{sampler.js → system-metrics-sampler.js}

@@ -5,10 +5,11 @@
 
 'use strict'
 
-const NAMES = require('./metrics/names')
-const logger = require('./logger').child({ component: 'sampler' })
+const os = require('node:os')
+const logger = require('./logger').child({ component: 'system-metrics-sampler' })
 const Timer = require('./timer')
-const os = require('os')
+
+const NAMES = require('./metrics/names')
 
 /*
  *
@@ -22,12 +23,12 @@ const SAMPLE_INTERVAL = 15 * MILLIS
 
 let samplers = []
 
-function Sampler(sampler, interval) {
+function SystemMetricsSampler(sampler, interval) {
   this.id = setInterval(sampler, interval)
   this.id.unref()
 }
 
-Sampler.prototype.stop = function stop() {
+SystemMetricsSampler.prototype.stop = function stop() {
   clearInterval(this.id)
 }
 
@@ -148,8 +149,8 @@ module.exports = {
   nativeMetrics: null,
 
   start: function start(agent) {
-    samplers.push(new Sampler(sampleMemory(agent), 5 * MILLIS))
-    samplers.push(new Sampler(checkEvents(agent), SAMPLE_INTERVAL))
+    samplers.push(new SystemMetricsSampler(sampleMemory(agent), 5 * MILLIS))
+    samplers.push(new SystemMetricsSampler(checkEvents(agent), SAMPLE_INTERVAL))
 
     // This requires a native module which may have failed to build.
     if (agent.config.plugins.native_metrics.enabled && !this.nativeMetrics) {
@@ -175,17 +176,17 @@ module.exports = {
 
       // Add GC events if available.
       if (this.nativeMetrics.gcEnabled) {
-        samplers.push(new Sampler(sampleGc(agent, this.nativeMetrics), SAMPLE_INTERVAL))
+        samplers.push(new SystemMetricsSampler(sampleGc(agent, this.nativeMetrics), SAMPLE_INTERVAL))
       }
 
       // Add loop metrics if available.
       if (this.nativeMetrics.loopEnabled) {
-        samplers.push(new Sampler(sampleLoop(agent, this.nativeMetrics), SAMPLE_INTERVAL))
+        samplers.push(new SystemMetricsSampler(sampleLoop(agent, this.nativeMetrics), SAMPLE_INTERVAL))
       }
     }
 
     // Add CPU sampling using the built-in data (introduced in 6.1.0)
-    samplers.push(new Sampler(sampleCpu(agent), SAMPLE_INTERVAL))
+    samplers.push(new SystemMetricsSampler(sampleCpu(agent), SAMPLE_INTERVAL))
 
     this.state = 'running'
   },

package/lib/transaction/index.js

@@ -15,7 +15,6 @@ const props = require('../util/properties')
 const Timer = require('../timer')
 const Trace = require('./trace')
 const synthetics = require('../synthetics')
-const url = require('url')
 const urltils = require('../util/urltils')
 const TraceContext = require('./tracecontext').TraceContext
 const Logs = require('./logs')
@@ -609,49 +608,6 @@ Transaction.prototype.getFullName = function getFullName() {
   return fullName
 }
 
-/**
- * Returns the full URL of the transaction with query, search, or hash portions
- * removed. This is only applicable for web transactions.
- *
- * Caches to ._scrubbedUrl, pulls in from .parsedUrl if it is available,
- * otherwise it will parse .url, store it on .parsedUrl, then scrub the URL and
- * store it in the cache.
- *
- * @returns {(string|undefined)} Returns a string or undefined.
- */
-Transaction.prototype.getScrubbedUrl = function getScrubbedUrl() {
-  if (!this.isWeb()) {
-    return
-  }
-  if (this._scrubbedUrl) {
-    return this._scrubbedUrl
-  }
-
-  // If we don't have a parsedUrl, lets populate it from .url
-  if (!this.parsedUrl) {
-    // At time of writing .url should always be set by the time we get here
-    // because that is what .isWeb() checks against. In the future it may be
-    // instead checking a enum or other property so guard ourselves just in
-    // case.
-    if (!this.url) {
-      return
-    }
-
-    this.parsedUrl = url.parse(this.url)
-  }
-
-  const scrubbedParsedUrl = Object.assign(Object.create(null), this.parsedUrl)
-  scrubbedParsedUrl.search = null
-  scrubbedParsedUrl.query = null
-  scrubbedParsedUrl.href = null
-  scrubbedParsedUrl.path = null
-  scrubbedParsedUrl.hash = null
-
-  this._scrubbedUrl = url.format(scrubbedParsedUrl)
-
-  return this._scrubbedUrl
-}
-
 /**
  * The instrumentation associates metrics with the different kinds of trace
  * segments. The metrics recorders are dependent on the transaction name to
@@ -779,11 +735,12 @@ Transaction.prototype.alternatePathHashes = function alternatePathHashes() {
  * an attribute onto the exception.
  *
  * @param {Exception} exception  The exception object to be collected.
+ * @param {Segment}   segment    The segment to which the exception is linked.
  */
 Transaction.prototype._linkExceptionToSegment = _linkExceptionToSegment
 
-function _linkExceptionToSegment(exception) {
-  const segment = this.agent.tracer.getSegment()
+function _linkExceptionToSegment(exception, segment) {
+  segment = segment || this.agent.tracer.getSegment()
   if (!segment) {
     return
   }
@@ -806,16 +763,17 @@ function _linkExceptionToSegment(exception) {
  * the exception will be collected along with the transaction details.
  *
  * @param {Exception}   exception  The exception object to be collected.
+ * @param {Segment}     segment    The segment to which the exception is linked.
  */
 Transaction.prototype.addException = _addException
 
-function _addException(exception) {
+function _addException(exception, segment) {
   if (!this.isActive()) {
     logger.trace('Transaction is not active. Not capturing error: ', exception)
     return
   }
 
-  this._linkExceptionToSegment(exception)
+  this._linkExceptionToSegment(exception, segment)
   this.exceptions.push(exception)
 }
 

package/lib/transaction/trace/segment.js

@@ -64,6 +64,9 @@ function TraceSegment({ id, config, name, collect, parentId, root, isRoot = fals
   this.state = STATE.EXTERNAL
   this.async = true
   this.ignore = false
+  // only use to specify spanKind on segments created with `api.startBackgroundTransaction` and `api.startWebTransaction`
+  // we typically determine the span kind based on the segment name
+  this.spanKind = null
 }
 
 TraceSegment.prototype.getSpanContext = function getSpanContext() {

package/lib/transaction/tracer/index.js

@@ -222,10 +222,11 @@ function transactionNestProxy(type, handler) {
 
     // don't nest transactions, reuse existing ones
     let context = tracer.getContext()
+    const transaction = tracer.getTransaction()
 
     let createNew = false
 
-    if (!context?.transaction || context?.transaction.type !== type) {
+    if (!transaction || transaction.type !== type) {
       createNew = true
     }
 

package/package.json

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