feat: adaptive.sampling_target can be set under sampler sections (#3532)

Author: amychisholm03

lib/agent.js

@@ -290,8 +290,10 @@ function Agent(config) {
 
   // Instantiate sampling decisions.
   this.sampler = {}
-  // TODO: This could create duplicate AdaptiveSampler instances of the same
-  // `sampling_target`, fix will be addressed in https://github.com/newrelic/node-newrelic/issues/3519.
+  // This is the global adaptive sampler instance used across
+  // different sampling modes and not intended to be used directly.
+  this.sampler._globalAdaptiveSampler = null
+  // The samplers to use for a particular sampler mode.
   this.sampler.root = determineSampler({ agent: this, config, sampler: 'root' })
   this.sampler.remoteParentSampled = determineSampler({ agent: this, config, sampler: 'remote_parent_sampled' })
   this.sampler.remoteParentNotSampled = determineSampler({ agent: this, config, sampler: 'remote_parent_not_sampled' })
@@ -850,10 +852,17 @@ Agent.prototype._listenForConfigChanges = function _listenForConfigChanges() {
     self.txSegmentNormalizer.load.apply(self.txSegmentNormalizer, arguments)
   })
   this.config.on('sampling_target', function updateSamplingTarget(target) {
-    self.sampler.root.samplingTarget = target
+    // Remember config.sampling_target is an alias for
+    // config.distributed_tracing.sampler.adaptive_sampling_target,
+    // which is the sampling target for the global adaptive sampler.
+    if (self.sampler._globalAdaptiveSampler) {
+      self.sampler._globalAdaptiveSampler.samplingTarget = target
+    }
   })
   this.config.on('sampling_target_period_in_seconds', function updateSamplePeriod(period) {
-    self.sampler.root.samplingPeriod = period * 1000
+    if (self.sampler._globalAdaptiveSampler) {
+      self.sampler._globalAdaptiveSampler.samplingPeriod = period * 1000
+    }
   })
   this.config.on('event_harvest_config', function onHarvestConfigReceived(harvestConfig) {
     if (harvestConfig) {

lib/config/index.js

@@ -25,7 +25,7 @@ const mergeServerConfig = new MergeServerConfig()
 const { boolean: isTruthular } = require('./formatters')
 const configDefinition = definition()
 const parseLabels = require('../util/label-parser')
-const { buildTraceIdRatioSamplers, setTraceIdRatioSamplerFromEnv } = require('./samplers')
+const { buildSamplers, setSamplersFromEnv } = require('./samplers')
 
 /**
  * CONSTANTS -- we gotta lotta 'em
@@ -125,6 +125,8 @@ function Config(config) {
   this.trusted_account_ids = null
   this.trusted_account_key = null
 
+  // The global sampling target for AdaptiveSamplers that do not
+  // specify their own sampling_target
   this.sampling_target = this.distributed_tracing.sampler.adaptive_sampling_target
   this.sampling_target_period_in_seconds = 60
   this.max_payload_size_in_bytes = DEFAULT_MAX_PAYLOAD_SIZE_IN_BYTES
@@ -1065,8 +1067,8 @@ Config.prototype._fromPassed = function _fromPassed(external, internal, arbitrar
       continue
     }
 
-    // Handle trace_id_ratio_based for distributed tracing sampler configuration
-    buildTraceIdRatioSamplers({ config: external, key, incomingConfig: internal, logger })
+    // Handle object-based distributed tracing sampler configurations
+    buildSamplers({ config: external, key, configToUpdate: internal, logger })
 
     if (key === 'ssl' && !isTruthular(external.ssl)) {
       logger.warn(SSL_WARNING)
@@ -1207,10 +1209,11 @@ Config.prototype._fromEnvironment = function _fromEnvironment(
       setFromEnv({ config, key, paths, envVar, formatter: value.formatter })
 
       // Handle custom configuration of the sampler if it's set to trace_id_ratio_based
-      // since sampler was set to a string but now has to be converted to an object.
-      // This is called here because we need set the sampler to a value first in config before setting
-      // trace id ratio sampler (if the user set that)
-      setTraceIdRatioSamplerFromEnv({
+      // or adaptive with adaptive.sampling_target defined, since sampler was set to a
+      // string but now has to be converted to an object.
+      // This is called here because we need to set the sampler to a value first in config
+      // before setting the samplers.
+      setSamplersFromEnv({
         key,
         config,
         paths,

lib/config/samplers.js

@@ -4,7 +4,7 @@
  */
 
 'use strict'
-const { allowList, float } = require('./formatters')
+const { allowList, float, int } = require('./formatters')
 
 /**
  * This configuration is currently the same for `distributed_tracing.sampler` and `distributed_tracing.sampler.partial_granularity`
@@ -62,28 +62,46 @@ const config = {
 }
 
 /**
- * Builds the trace_id_ratio_based for distributed tracing sampler configuration structure
+ * Builds the `trace_id_ratio_based.ratio` and `adaptive.sampling_target`
+ * for distributed tracing sampler configuration structure.
  *
  * @param {object} params to function
  * @param {object} params.config - The full configuration object
  * @param {string} params.key - The configuration key being processed
- * @param {object} params.incomingConfig The internal configuration object being modified
+ * @param {object} params.configToUpdate - The internal configuration object being modified
  * @param {Logger} params.logger - The logger instance
  */
-function buildTraceIdRatioSamplers({ config, key, incomingConfig, logger }) {
+function buildSamplers({ config, key, configToUpdate, logger }) {
   if (!isValidDTSampler(key)) {
     return
   }
 
   const samplerConfig = config[key]
   const samplers = Object.keys(samplerConfig)
 
-  // user can set multiple samplers
+  // user can set the following samplers:
+  // 'root', 'remote_parent_sampled', and `remote_parent_not_sampled'
+  // under 'distributed_tracing.sampler` and `distributed_tracing.sampler.partial_granularity`
   for (const sampler of samplers) {
+    if (isAdaptiveSamplingTargetConfig(sampler, samplerConfig)) {
+      const samplingValue = samplerConfig[sampler].adaptive.sampling_target
+      // sampling_target is an int [1, 120]
+      if (samplingValue && samplingValue >= 1 && samplingValue <= 120) {
+        configToUpdate[key][sampler] = {
+          adaptive: {
+            sampling_target: samplingValue
+          }
+        }
+        logger.trace('Setting adaptive.sampling_target on %s.%s', key, sampler)
+      } else {
+        logger.trace('Not setting adaptive.sampling_target on %s.%s as value is not in range [1,120].', key, sampler)
+      }
+    }
+
     if (isTraceIdRatioBasedConfig(sampler, samplerConfig)) {
       const ratioValue = samplerConfig[sampler].trace_id_ratio_based.ratio
-      if (ratioValue) {
-        incomingConfig[key][sampler] = {
+      if (typeof ratioValue === 'number') {
+        configToUpdate[key][sampler] = {
           trace_id_ratio_based: {
             ratio: ratioValue
           }
@@ -96,6 +114,69 @@ function buildTraceIdRatioSamplers({ config, key, incomingConfig, logger }) {
   }
 }
 
+/**
+ * Assigns the value of the distributed tracing samplers env var as an
+ * trace_id_ratio_based or adaptive object to the sampler in the config.
+ *
+ * @param {object} params object passed to fn
+ * @param {string} params.key key of the sampler
+ * Example: 'root' or 'remote_parent_sampled'
+ * @param {object} params.config agent config
+ * @param {Array} params.paths list of leaf nodes leading to the sampling configuration value
+ * Example: ['distributed_tracing', 'sampler']
+ * @param {Function} params.setNestedKey function to set nested key in config
+ * @param {Logger} params.logger logger instance
+ */
+function setSamplersFromEnv({ key, config, paths, setNestedKey, logger }) {
+  if (paths.length === 0) {
+    return
+  }
+
+  const lastPath = paths[paths.length - 1]
+  if (!isValidDTSampler(lastPath) || !isValidDTSamplerType(key)) {
+    return
+  }
+
+  const nestedValue = getNestedValue(config, [...paths, key])
+
+  if (nestedValue === 'trace_id_ratio_based') {
+    handleTraceIdRatioBased({ paths, key, config, setNestedKey, logger })
+  } else if (nestedValue === 'adaptive') {
+    handleAdaptiveSampling({ paths, key, config, setNestedKey, logger })
+  }
+}
+
+function handleTraceIdRatioBased({ paths, key, config, setNestedKey, logger }) {
+  const envVar = `NEW_RELIC_${[...paths, key, 'trace_id_ratio_based', 'ratio'].join('_').toUpperCase()}`
+  const setting = process.env[envVar]
+
+  if (setting) {
+    const formattedSetting = float(setting)
+    setNestedKey(config, [...paths, key], { trace_id_ratio_based: { ratio: formattedSetting } })
+    logger.trace('Setting %s environment variable to %s', envVar, formattedSetting)
+  } else {
+    logger.trace('Not setting %s environment variable. Setting %s.%s to `default`', envVar, paths.join('.'), key)
+    setNestedKey(config, [...paths, key], 'default')
+  }
+}
+
+function handleAdaptiveSampling({ paths, key, config, setNestedKey, logger }) {
+  const envVar = `NEW_RELIC_${[...paths, key, 'adaptive', 'sampling_target'].join('_').toUpperCase()}`
+  const setting = process.env[envVar]
+  const formattedSetting = int(setting)
+
+  if (formattedSetting >= 1 && formattedSetting <= 120) {
+    setNestedKey(config, [...paths, key], { adaptive: { sampling_target: formattedSetting } })
+    logger.trace('Setting %s environment variable to %s', envVar, formattedSetting)
+  } else {
+    logger.trace('Not setting %s environment variable; value not in range [1,120]. Setting %s.%s as `adaptive` with no `sampling_target',
+      envVar,
+      paths.join('.'),
+      key)
+    setNestedKey(config, [...paths, key], 'adaptive')
+  }
+}
+
 /**
  * Checks if the external config contains a trace_id_ratio_based for distributed tracing
  * sampler configuration
@@ -111,7 +192,21 @@ function isTraceIdRatioBasedConfig(sampler, samplerConfig) {
 }
 
 /**
- * Check if the sampler is a valid value of either 'sampler' or 'partial_granularity'
+ * Checks if the external config contains a adaptive object
+ * for distributed tracing sampler configuration
+ *
+ * @param {string} sampler - The selected sampler key
+ * @param {object} samplerConfig - The sampler configuration object
+ * @returns {boolean} true if it's a adaptive config
+ */
+function isAdaptiveSamplingTargetConfig(sampler, samplerConfig) {
+  return isValidDTSamplerType(sampler) &&
+   typeof samplerConfig[sampler] === 'object' &&
+    'adaptive' in samplerConfig[sampler]
+}
+
+/**
+ * Check if the sampler is a valid value of either 'sampler', 'full_granularity', or 'partial_granularity'
  * @param {string} sampler - The sampler key to validate
  * @returns {boolean} true if valid, false otherwise
  */
@@ -128,47 +223,6 @@ function isValidDTSamplerType(samplerType) {
   return ['root', 'remote_parent_sampled', 'remote_parent_not_sampled'].includes(samplerType)
 }
 
-/**
- * Assigns the value of the distributed tracing samplers env var as an trace_id_ratio_based
- * object to the sampler in the config.
- *
- * @param {object} params object passed to fn
- * @param {string} params.key key of the sampler
- * Example: 'root' or 'remote_parent_sampled'
- * @param {object} params.config agent config
- * @param {Array} params.paths list of leaf nodes leading to the sampling configuration value
- * Example: ['distributed_tracing', 'sampler']
- * @param {Function} params.setNestedKey function to set nested key in config
- * @param {Logger} params.logger logger instance
- */
-function setTraceIdRatioSamplerFromEnv({ key, config, paths, setNestedKey, logger }) {
-  // trace id ratio based sampler is nested in leaf nodes under distributed_tracing > samplers > key
-  // so don't continue if path is empty
-  if (paths.length === 0) {
-    return
-  }
-
-  const lastPath = paths[paths.length - 1]
-  if (isValidDTSampler(lastPath) && isValidDTSamplerType(key)) {
-    // Get the value of `config.distributed_tracing.sampler[key]` or `config.distributed_tracing.sampler.partial_granularity[key]`
-    const nestedValue = getNestedValue(config, [...paths, key])
-    if (nestedValue !== 'trace_id_ratio_based') {
-      return
-    }
-
-    // set the trace id based ratio
-    const envVar = `NEW_RELIC_${[...paths, key, 'trace_id_ratio_based', 'ratio'].join('_').toUpperCase()}`
-    const setting = process.env[envVar]
-    if (setting) {
-      const formattedSetting = float(setting)
-      setNestedKey(config, [...paths, key], { trace_id_ratio_based: { ratio: formattedSetting } })
-      logger.trace('Setting %s environment variable to %s', envVar, formattedSetting)
-    } else {
-      logger.trace('Not setting %s environment variable. Setting %s.%s to `default`', envVar, paths.join('.'), key)
-      setNestedKey(config, [...paths, key], 'default')
-    }
-  }
-}
 /**
  * Retrieves a value from a nested object by providing the list of parent keys.
  * @param {object} obj object to assign value to
@@ -190,6 +244,6 @@ function getNestedValue(obj, keys) {
 
 module.exports = {
   config,
-  buildTraceIdRatioSamplers,
-  setTraceIdRatioSamplerFromEnv
+  buildSamplers,
+  setSamplersFromEnv
 }

lib/samplers/README.md

@@ -4,7 +4,7 @@ The New Relic agent supports a robust sampling decision making interface. This i
 
 ## Config
 
-Customers configure how they would like their transactions to be sampled under our `distributed_tracing` section in our config. Remember, sampling will only apply if a customer has `distributed_tracing.enabled` set to `true`.
+Customers configure how they would like their transactions to be sampled under our `distributed_tracing` section in our config. Remember, sampling will only apply if a customer has `distributed_tracing.enabled` set to `true`, `distributed_tracing.sampler.full_granularity.enabled = true`, and if they want partial granularity traces, `distributed_tracing.sampler.partial_granularity.enabled = true`.
 
 ### Types
 
@@ -13,10 +13,13 @@ Customers configure how they would like their transactions to be sampled under o
   - `root`: This is the main sampler for traces originating from the current service.
   - `remote_parent_sampled`: The sampler for when the upstream service has sampled the trace.
   - `remote_parent_not_sampled`: The sampler for when the upstream service has not sampled the trace.
+- `SAMPLER_TYPE` can be `adaptive`, `always_on`, `always_off`, and `trace_id_ratio_based`.
+- `SAMPLER_SUBOPTION` is only valid for `adaptive` and `trace_id_ratio_based` and only required for `trace_id_ratio_based`. `adaptive` will fall back to a global `AdaptiveSampler` with a sampling target defined by `distributed_tracing.sampler.adaptive_sampling_target` if `adaptive.sampling_target` is not given.
 
 NOTE: `distributed_tracing.sampler` will be used as the setting for the full granularity samplers.
 
 ### Full Config in Accordance to Spec
+Full Config in Accordance to Pending Spec Changes (as of agent team discussions, 11/21/2025):
 
 ```yaml
 ...
@@ -30,12 +33,12 @@ distributed_tracing:
   exclude_newrelic_header: boolean (default false)
   enable_success_metrics (OPTIONAL): boolean (default true, set to false to disable supportability metrics)
   sampler: (section for sampling config options for different scenarios)
-    adaptive_sampling_target (see note on Sampling Target below)
+    adaptive_sampling_target (see note on Sampling Target above)
     root: (when the trace originates from the current service)
-      ${SAMPLER_TYPE} (See `Sampler Options` below)
+      ${SAMPLER_TYPE} (See `Sampler Options` above)
         ${SAMPLER_SUBOPTION}
     remote_parent_sampled: (when the upstream service has sampled the trace)
-      ${SAMPLER_TYPE} (See `Sampler Options` below)
+      ${SAMPLER_TYPE})
         ${SAMPLER_SUBOPTION}
     remote_parent_not_sampled: (when the upstream service has not sampled the trace)
       ${SAMPLER_TYPE}
@@ -46,10 +49,10 @@ distributed_tracing:
       enabled
       type   ("reduced", "essential", "compact")
       root: (when the trace originates from the current service)
-        ${SAMPLER_TYPE} (See `Sampler Options` below)
+        ${SAMPLER_TYPE}
           ${SAMPLER_SUBOPTION}
       remote_parent_sampled: (when the upstream service has sampled the trace)
-        ${SAMPLER_TYPE} (See `Sampler Options` below)
+        ${SAMPLER_TYPE}
           ${SAMPLER_SUBOPTION}
       remote_parent_not_sampled: (when the upstream service has not sampled the trace)
         ${SAMPLER_TYPE}
@@ -59,9 +62,9 @@ distributed_tracing:
 
 ## Solution
 
-There are three sampler modes, each with three sampler sections, resulting in potentially nine different sampling decisions that the agent would have to support. We create a new `Sampler` instance (`AdaptiveSampler`, `AlwaysOnSampler`, `AlwaysOffSampler`, or `TraceIdRatioBasedSampler`, defined in this folder) for each of these sampler modes' sections.
+There are two sampler modes, each with three sampler sections, resulting in potentially six different sampling decisions that the agent would have to support. We create a new `Sampler` instance (`AdaptiveSampler`, `AlwaysOnSampler`, `AlwaysOffSampler`, or `TraceIdRatioBasedSampler`, defined in this folder) for each of these sampler modes' sections.
 
-`agent.sampler` would be defined as:
+`agent.sampler` is defined as:
 
 * `agent.sampler.root`
 * `agent.sampler.remoteParentSampled`
@@ -72,4 +75,4 @@ There are three sampler modes, each with three sampler sections, resulting in po
 
 These samplers have a `applySamplingDecision({transaction})` function, which `Transaction` calls (in `lib/transaction/index.js`) to update its `sampled` field and therefore its `priority`.
 
-Unlike the other samplers, the `AdaptiveSampler` must share state with other `AdaptiveSamplers` with the same `sampling_target`, which complicates our seperate sampler instances approach. This will be fixed shortly, and this document will be updated to describe that solution.
+Unlike the other samplers, the `AdaptiveSampler` must share state with other `AdaptiveSampler`s if they do not have their suboption, `sampling_target,` defined. Thus, this introduces our seventh field on `agent.sampler.*`: `agent.sampler._globalAdaptiveSampler `. The intent of this field is to have one instance of an `AdaptiveSampler` for `adaptive` sampler sections that do not specify an `adaptive.sampling_target` to share.

lib/samplers/adaptive-sampler.js

@@ -22,8 +22,11 @@ class AdaptiveSampler extends Sampler {
     this._seen = 0
     this._sampled = 0
     this._samplingPeriod = 0
-    this._samplingTarget = opts.target
-    this._maxSamples = 2 * opts.target
+    // sampling target cannot be a float
+    // config should enforce that values outside
+    // of [1,120] are not allowed
+    this._samplingTarget = parseInt(opts.target, 10)
+    this._maxSamples = 2 * this._samplingTarget
     this._samplingThreshold = 0
     this._resetCount = 0
     this._resetInterval = null