feat: Support honoring W3C traceparent sampled flag (#3009)

Author: jsumners-nr

THIRD_PARTY_NOTICES.md

@@ -91,7 +91,7 @@ code, the source code can be found at [https://github.com/newrelic/node-newrelic
 
 ### @grpc/grpc-js
 
-This product includes source derived from [@grpc/grpc-js](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js) ([v1.13.0](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js/tree/v1.13.0)), distributed under the [Apache-2.0 License](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js/blob/v1.13.0/LICENSE):
+This product includes source derived from [@grpc/grpc-js](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js) ([v1.12.4](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js/tree/v1.12.4)), distributed under the [Apache-2.0 License](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js/blob/v1.12.4/LICENSE):
 
 ```
                                  Apache License
@@ -509,7 +509,7 @@ This product includes source derived from [@grpc/proto-loader](https://github.co
 
 ### @newrelic/security-agent
 
-This product includes source derived from [@newrelic/security-agent](https://github.com/newrelic/csec-node-agent) ([v2.3.2](https://github.com/newrelic/csec-node-agent/tree/v2.3.2)), distributed under the [UNKNOWN License](https://github.com/newrelic/csec-node-agent/blob/v2.3.2/LICENSE):
+This product includes source derived from [@newrelic/security-agent](https://github.com/newrelic/csec-node-agent) ([v2.3.1](https://github.com/newrelic/csec-node-agent/tree/v2.3.1)), distributed under the [UNKNOWN License](https://github.com/newrelic/csec-node-agent/blob/v2.3.1/LICENSE):
 
 ```
 ## New Relic Software License v1.0
@@ -1271,7 +1271,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ### import-in-the-middle
 
-This product includes source derived from [import-in-the-middle](https://github.com/nodejs/import-in-the-middle) ([v1.13.1](https://github.com/nodejs/import-in-the-middle/tree/v1.13.1)), distributed under the [Apache-2.0 License](https://github.com/nodejs/import-in-the-middle/blob/v1.13.1/LICENSE):
+This product includes source derived from [import-in-the-middle](https://github.com/nodejs/import-in-the-middle) ([v1.13.0](https://github.com/nodejs/import-in-the-middle/tree/v1.13.0)), distributed under the [Apache-2.0 License](https://github.com/nodejs/import-in-the-middle/blob/v1.13.0/LICENSE):
 
 ```
                                  Apache License
@@ -1615,14 +1615,13 @@ IN THE SOFTWARE.
 
 ### require-in-the-middle
 
-This product includes source derived from [require-in-the-middle](https://github.com/nodejs/require-in-the-middle) ([v7.5.2](https://github.com/nodejs/require-in-the-middle/tree/v7.5.2)), distributed under the [MIT License](https://github.com/nodejs/require-in-the-middle/blob/v7.5.2/LICENSE):
+This product includes source derived from [require-in-the-middle](https://github.com/elastic/require-in-the-middle) ([v7.4.0](https://github.com/elastic/require-in-the-middle/tree/v7.4.0)), distributed under the [MIT License](https://github.com/elastic/require-in-the-middle/blob/v7.4.0/LICENSE):
 
 ```
 The MIT License (MIT)
 
 Copyright (c) 2016-2019, Thomas Watson Steen
-Copyright (c) 2019-2025, Elasticsearch B.V.
-Copyright (c) 2025+, require-in-the-middle contributors
+Copyright (c) 2019-2023, Elasticsearch B.V.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -1646,7 +1645,7 @@ SOFTWARE.
 
 ### semver
 
-This product includes source derived from [semver](https://github.com/npm/node-semver) ([v7.7.1](https://github.com/npm/node-semver/tree/v7.7.1)), distributed under the [ISC License](https://github.com/npm/node-semver/blob/v7.7.1/LICENSE):
+This product includes source derived from [semver](https://github.com/npm/node-semver) ([v7.6.3](https://github.com/npm/node-semver/tree/v7.6.3)), distributed under the [ISC License](https://github.com/npm/node-semver/blob/v7.6.3/LICENSE):
 
 ```
 The ISC License
@@ -1702,7 +1701,7 @@ SOFTWARE.
 
 ### @aws-sdk/client-s3
 
-This product includes source derived from [@aws-sdk/client-s3](https://github.com/aws/aws-sdk-js-v3) ([v3.758.0](https://github.com/aws/aws-sdk-js-v3/tree/v3.758.0)), distributed under the [Apache-2.0 License](https://github.com/aws/aws-sdk-js-v3/blob/v3.758.0/LICENSE):
+This product includes source derived from [@aws-sdk/client-s3](https://github.com/aws/aws-sdk-js-v3) ([v3.714.0](https://github.com/aws/aws-sdk-js-v3/tree/v3.714.0)), distributed under the [Apache-2.0 License](https://github.com/aws/aws-sdk-js-v3/blob/v3.714.0/LICENSE):
 
 ```
                                 Apache License
@@ -1911,7 +1910,7 @@ This product includes source derived from [@aws-sdk/client-s3](https://github.co
 
 ### @aws-sdk/s3-request-presigner
 
-This product includes source derived from [@aws-sdk/s3-request-presigner](https://github.com/aws/aws-sdk-js-v3) ([v3.758.0](https://github.com/aws/aws-sdk-js-v3/tree/v3.758.0)), distributed under the [Apache-2.0 License](https://github.com/aws/aws-sdk-js-v3/blob/v3.758.0/LICENSE):
+This product includes source derived from [@aws-sdk/s3-request-presigner](https://github.com/aws/aws-sdk-js-v3) ([v3.714.0](https://github.com/aws/aws-sdk-js-v3/tree/v3.714.0)), distributed under the [Apache-2.0 License](https://github.com/aws/aws-sdk-js-v3/blob/v3.714.0/LICENSE):
 
 ```
                                 Apache License
@@ -3739,7 +3738,7 @@ SOFTWARE.
 
 ### eslint-plugin-jsdoc
 
-This product includes source derived from [eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc) ([v50.6.8](https://github.com/gajus/eslint-plugin-jsdoc/tree/v50.6.8)), distributed under the [BSD-3-Clause License](https://github.com/gajus/eslint-plugin-jsdoc/blob/v50.6.8/LICENSE):
+This product includes source derived from [eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc) ([v50.6.1](https://github.com/gajus/eslint-plugin-jsdoc/tree/v50.6.1)), distributed under the [BSD-3-Clause License](https://github.com/gajus/eslint-plugin-jsdoc/blob/v50.6.1/LICENSE):
 
 ```
 Copyright (c) 2018, Gajus Kuizinas (http://gajus.com/)
@@ -3771,7 +3770,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 ### eslint
 
-This product includes source derived from [eslint](https://github.com/eslint/eslint) ([v9.22.0](https://github.com/eslint/eslint/tree/v9.22.0)), distributed under the [MIT License](https://github.com/eslint/eslint/blob/v9.22.0/LICENSE):
+This product includes source derived from [eslint](https://github.com/eslint/eslint) ([v9.17.0](https://github.com/eslint/eslint/tree/v9.17.0)), distributed under the [MIT License](https://github.com/eslint/eslint/blob/v9.17.0/LICENSE):
 
 ```
 Copyright OpenJS Foundation and other contributors, <www.openjsf.org>
@@ -4089,7 +4088,7 @@ THE SOFTWARE.
 
 ### koa
 
-This product includes source derived from [koa](https://github.com/koajs/koa) ([v2.16.0](https://github.com/koajs/koa/tree/v2.16.0)), distributed under the [MIT License](https://github.com/koajs/koa/blob/v2.16.0/LICENSE):
+This product includes source derived from [koa](https://github.com/koajs/koa) ([v2.15.3](https://github.com/koajs/koa/tree/v2.15.3)), distributed under the [MIT License](https://github.com/koajs/koa/blob/v2.15.3/LICENSE):
 
 ```
 (The MIT License)

lib/agent.js

@@ -303,6 +303,10 @@ function Agent(config) {
 }
 util.inherits(Agent, EventEmitter)
 
+Object.defineProperty(Agent.prototype, Symbol.toStringTag, {
+  value: 'Agent'
+})
+
 /**
  * The agent is meant to only exist once per application, but the singleton is
  * managed by index.js. An agent will be created even if the agent's disabled by

lib/config/default.js

@@ -1083,6 +1083,7 @@ defaultConfig.definition = () => ({
       }
     }
   },
+
   /**
    * Controls the method of cross agent tracing in the agent.
    * Distributed tracing lets you see the path that a request takes through your
@@ -1109,8 +1110,41 @@ defaultConfig.definition = () => ({
     exclude_newrelic_header: {
       formatter: boolean,
       default: false
+    },
+
+    sampler: {
+      /**
+       * When set to `always_on`, the sampled flag in the `traceparent` header
+       * being set to "true" will result in the local transaction being sampled
+       * with a priority value of "2". When set to `always_off`, the local
+       * transaction will never be sampled. At the default setting, the sampling
+       * decision will be determined according to the normal algorithm.
+       *
+       * This setting takes precedence over the `remote_parent_not_sampled`
+       * setting.
+       */
+      remote_parent_sampled: {
+        formatter: allowList.bind(null, ['always_on', 'always_off', 'default']),
+        default: 'default'
+      },
+
+      /**
+       * When set to `always_on`, the local transaction will be sampled with a
+       * priority of "2".
+       * When set to `always_off`, the local transaction will never be sampled.
+       * At the default setting, the sampling decision will be determined
+       * according to the normal algorithm.
+       *
+       * This setting only affects decisions when the traceparent sampled flag
+       * is set to 0.
+       */
+      remote_parent_not_sampled: {
+        formatter: allowList.bind(null, ['always_on', 'always_off', 'default']),
+        default: 'default'
+      }
     }
   },
+
   /**
    * Controls the use of cross-application tracing.
    *

lib/otel/segments/utils.js

@@ -5,6 +5,8 @@
 
 'use strict'
 
+const Traceparent = require('../../w3c/traceparent')
+
 /**
  * Accepts trace context payload if span has a parent. It will use the
  * span context to extract the traceId, traceFlags and trace state.
@@ -20,8 +22,12 @@ function propagateTraceContext({ transaction, otelSpan, transport }) {
 
   if (parentSpanId) {
     // prefix traceFlags with 0 as it is stored as a parsed int on spanContext
-    const traceparent = `00-${spanContext.traceId}-${parentSpanId}-0${spanContext.traceFlags}`
-    transaction.acceptTraceContextPayload(traceparent, spanContext?.traceState?.state, transport)
+    const traceparent = new Traceparent({
+      traceId: spanContext.traceId,
+      parentId: parentSpanId,
+      flags: `0${spanContext.traceFlags}`
+    })
+    transaction.acceptTraceContextPayload(traceparent.toString(), spanContext?.traceState?.state, transport)
   }
 }
 

lib/shim/message-shim/subscribe-consume.js

@@ -141,7 +141,7 @@ function makeWrapConsumer({ spec, queue, destinationName, destNameIsArg }) {
  */
 function createConsumerWrapper({ shim, spec, consumer }) {
   return function createConsumeTrans() {
-    // If there is no transaction or we're in a pre-existing transaction,
+    // If there is no transaction, or we're in a pre-existing transaction,
     // then don't do anything. Note that the latter should never happen.
     const args = shim.argsToArray.apply(shim, arguments)
     const tx = shim.tracer.getTransaction()

lib/transaction/index.js

@@ -888,13 +888,12 @@ function acceptDistributedTraceHeaders(transportType, headers) {
   const transport = TRANSPORT_TYPES_SET[transportType] ? transportType : TRANSPORT_TYPES.UNKNOWN
 
   // assumes header keys already lowercase
-  const traceparent = headers[TRACE_CONTEXT_PARENT_HEADER]
+  const traceparentHeader = headers[TRACE_CONTEXT_PARENT_HEADER]?.toString('utf8')
+  const tracestateHeader = headers[TRACE_CONTEXT_STATE_HEADER]?.toString('utf8')
 
-  if (traceparent) {
+  if (traceparentHeader) {
     logger.trace('Accepting trace context DT payload for transaction %s', this.id)
-    // assumes header keys already lowercase
-    const tracestate = headers[TRACE_CONTEXT_STATE_HEADER]
-    this.acceptTraceContextPayload(traceparent, tracestate, transport)
+    this.acceptTraceContextPayload(traceparentHeader, tracestateHeader, transport)
   } else if (NEWRELIC_TRACE_HEADER in headers) {
     logger.trace('Accepting newrelic DT payload for transaction %s', this.id)
     // assumes header keys already lowercase
@@ -951,7 +950,7 @@ function checkForExistingNrTraceHeaders(headers) {
 }
 
 Transaction.prototype.acceptTraceContextPayload = acceptTraceContextPayload
-function acceptTraceContextPayload(traceparent, tracestate, transport) {
+function acceptTraceContextPayload(traceparentHeader, tracestateHeader, transport) {
   if (this.isDistributedTrace) {
     logger.warn(
       'Already accepted or created a distributed trace payload for transaction %s, ignoring call',
@@ -967,26 +966,111 @@ function acceptTraceContextPayload(traceparent, tracestate, transport) {
     return
   }
 
-  const traceContext = this.traceContext.acceptTraceContextPayload(traceparent, tracestate)
+  const { traceparent, tracestate } = this.traceContext.acceptTraceContextPayload(traceparentHeader, tracestateHeader)
+  if (traceparent === undefined) {
+    // If the traceparent wasn't accepted, there isn't anything to do. Per spec,
+    // the trace state should not be used if the traceparent is not provided
+    // or is not valid.
+    return
+  }
 
-  if (traceContext.acceptedTraceparent) {
-    this.acceptedDistributedTrace = true
-    this.isDistributedTrace = true
+  this.acceptedDistributedTrace = true
+  this.isDistributedTrace = true
 
-    this.traceId = traceContext.traceId
-    this.parentSpanId = traceContext.parentSpanId
-    this.parentTransportDuration = traceContext.transportDuration
-    this.parentTransportType = transport
+  this.traceId = traceparent.traceId
+  this.parentSpanId = traceparent.parentId
+  this.parentTransportType = transport
 
-    if (traceContext.acceptedTracestate) {
-      this.parentType = traceContext.parentType
-      this.parentAcct = traceContext.accountId
-      this.parentApp = traceContext.appId
-      this.parentId = traceContext.transactionId
-      this.sampled = traceContext.sampled
-      this.priority = traceContext.priority
+  if (tracestate !== undefined && tracestate.intrinsics?.isValid === true) {
+    // Add properties that are only available if we have a New Relic tracestate
+    // list member present.
+    this.parentType = tracestate.parentType
+    this.parentAcct = tracestate.parentAccountId
+    this.parentApp = tracestate.parentAppId
+    this.parentId = tracestate.transactionId
+    if (tracestate.timestamp != null) {
+      this.parentTransportDuration = Math.max(0, (Date.now() - tracestate.timestamp) / 1_000)
     }
   }
+
+  decideSamplingFromW3cData({ transaction: this, traceparent, tracestate })
+}
+
+/**
+ * Updates the transaction with sampling configuration as determined by the
+ * agent's distributed tracing sampler configuration. In short, updates the
+ * transaction to always sample, never sample, or let the standard sampling
+ * algorithm make the decision.
+ *
+ * @param {object} params Input parameters.
+ * @param {Transaction} params.transaction The transaction to update.
+ * @param {Traceparent} params.traceparent The object representation of a
+ * traceparent header.
+ * @param {Tracestate} params.tracestate The object representation of a
+ * tracestate header.
+ */
+function decideSamplingFromW3cData({ transaction, traceparent, tracestate }) {
+  const {
+    remote_parent_sampled: parentSampled,
+    remote_parent_not_sampled: parentNotSampled
+  } = transaction.agent.config.distributed_tracing.sampler
+  if (traceparent.isSampled === true) {
+    switch (parentSampled) {
+      case 'default': {
+        applyOriginalSamplingDecision({ transaction, tracestate })
+        break
+      }
+
+      case 'always_on': {
+        transaction.sampled = true
+        transaction.priority = 2.0
+        break
+      }
+
+      case 'always_off': {
+        transaction.sampled = false
+        transaction.priority = 0
+        break
+      }
+    }
+  } else if (traceparent.isSampled === false) {
+    switch (parentNotSampled) {
+      case 'default': {
+        applyOriginalSamplingDecision({ transaction, tracestate })
+        break
+      }
+
+      case 'always_on': {
+        transaction.sampled = true
+        transaction.priority = 2.0
+        break
+      }
+
+      case 'always_off': {
+        transaction.sampled = false
+        transaction.priority = 0
+        break
+      }
+    }
+  }
+}
+
+/**
+ * Sets the sampling decision according to the way we did things prior to
+ * adding support for honoring the W3C traceparent sampled flag.
+ *
+ * Note: this function only exists to appease the complexity linting rule.
+ *
+ * @param {object} params Function parameters.
+ * @param {Transaction} params.transaction The transaction to update.
+ * @param {Tracestate} params.tracestate A tracestate object with embedded
+ * New Relic intrinsics.
+ */
+function applyOriginalSamplingDecision({ transaction, tracestate }) {
+  // Our original implementation decided sampling based on the intrinsics
+  // within the New Relic listmember in the tracestate.
+  transaction.sampled = tracestate?.intrinsics ? tracestate.isSampled : null
+  transaction.priority = tracestate?.intrinsics ? tracestate.priority : null
 }
 
 /*