newrelic 13.6.6 → 13.7.0

package/lib/config/samplers.js

@@ -4,11 +4,10 @@
  */
 
 'use strict'
-const { allowList, float } = require('./formatters')
+const { allowList, float, int } = require('./formatters')
 
 /**
- * This configuration is currently the same for `distributed_tracing.sampler`,
- * `distributed_tracing.sampler.full_granularity` and `distributed_tracing.sampler.partial_granularity`
+ * This configuration is currently the same for `distributed_tracing.sampler` and `distributed_tracing.sampler.partial_granularity`
  * Note: This also just defines the outer structure.  These values are mixed data types. Most of the time
  * it is just a string. But if you want to use the `trace_id_ratio_based` sampler, then you need to
  * provide an object with a `ratio` property. All of that mapping is done in `lib/config/index.js`
@@ -27,8 +26,8 @@ const config = {
    * }
    */
   root: {
-    formatter: allowList.bind(null, ['trace_id_ratio_based', 'adaptive', 'always_on', 'always_off', 'default']),
-    default: 'default',
+    formatter: allowList.bind(null, ['trace_id_ratio_based', 'adaptive', 'always_on', 'always_off']),
+    default: 'adaptive',
   },
 
   /**
@@ -42,8 +41,8 @@ const config = {
    * setting.
    */
   remote_parent_sampled: {
-    formatter: allowList.bind(null, ['trace_id_ratio_based', 'adaptive', 'always_on', 'always_off', 'default']),
-    default: 'default',
+    formatter: allowList.bind(null, ['trace_id_ratio_based', 'adaptive', 'always_on', 'always_off']),
+    default: 'adaptive',
   },
 
   /**
@@ -57,21 +56,22 @@ const config = {
    * is set to 0.
    */
   remote_parent_not_sampled: {
-    formatter: allowList.bind(null, ['trace_id_ratio_based', 'adaptive', 'always_on', 'always_off', 'default']),
-    default: 'default',
+    formatter: allowList.bind(null, ['trace_id_ratio_based', 'adaptive', 'always_on', 'always_off']),
+    default: 'adaptive',
   }
 }
 
 /**
- * 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
   }
@@ -79,12 +79,29 @@ function buildTraceIdRatioSamplers({ config, key, incomingConfig, logger }) {
   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
           }
@@ -97,6 +114,71 @@ 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 `adaptive`', envVar, paths.join('.'), key)
+    setNestedKey(config, [...paths, key], 'adaptive')
+  }
+}
+
+function handleAdaptiveSampling({ paths, key, config, setNestedKey, logger }) {
+  const envVar = `NEW_RELIC_${[...paths, key, 'adaptive', 'sampling_target'].join('_').toUpperCase()}`
+  const setting = process.env[envVar]
+
+  if (setting) {
+    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,13 +193,27 @@ function isTraceIdRatioBasedConfig(sampler, samplerConfig) {
     'trace_id_ratio_based' in samplerConfig[sampler]
 }
 
+/**
+ * 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
  */
 function isValidDTSampler(sampler) {
-  return ['sampler', 'full_granularity', 'partial_granularity'].includes(sampler)
+  return ['sampler', 'partial_granularity'].includes(sampler)
 }
 
 /**
@@ -129,47 +225,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.full_granularity[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
@@ -191,6 +246,6 @@ function getNestedValue(obj, keys) {
 
 module.exports = {
   config,
-  buildTraceIdRatioSamplers,
-  setTraceIdRatioSamplerFromEnv
+  buildSamplers,
+  setSamplersFromEnv
 }

package/lib/feature_flags.js

@@ -32,7 +32,7 @@ exports.released = [
   'langchain_instrumentation',
   'native_metrics',
   'new_promise_tracking',
-  'opentelemetry_bridge',
+  'opentelemetry',
   'protocol_17',
   'released',
   'send_request_uri_attribute',

package/lib/instrumentation/koa/router-instrumentation.js

@@ -10,7 +10,8 @@ const { MiddlewareSpec, MiddlewareMounterSpec } = require('../../shim/specs')
 module.exports = function instrumentRouter(shim, Router) {
   shim.setFramework(shim.KOA)
 
-  const proto = Router.prototype
+  // @koa/router 15.x exports the Router class as the default export
+  const proto = Router.prototype || Router.default?.prototype
 
   shim.wrapReturn(proto, 'register', wrapMiddleware)
   shim.wrapReturn(proto, 'allowedMethods', wrapAllowedMethods)

package/lib/otel/logs/index.js

@@ -18,7 +18,7 @@ const defaultLogger = require('../../logger').child({ component: 'opentelemetry-
 const SetupSignal = require('../setup-signal.js')
 const NewRelicLoggerProvider = require('./proxying-provider.js')
 const NoOpExporter = require('./no-op-exporter.js')
-const normalizeTimestamp = require('./normalize-timestamp.js')
+const normalizeTimestamp = require('../normalize-timestamp.js')
 const severityToString = require('./severity-to-string.js')
 
 class SetupLogs extends SetupSignal {

package/lib/otel/metrics/index.js

@@ -23,8 +23,8 @@ class SetupMetrics extends SetupSignal {
     super({ agent, logger })
 
     const { config } = agent
-    const exportInterval = config.opentelemetry_bridge.metrics.exportInterval
-    const exportTimeout = config.opentelemetry_bridge.metrics.exportTimeout
+    const exportInterval = config.opentelemetry.metrics.exportInterval
+    const exportTimeout = config.opentelemetry.metrics.exportTimeout
 
     const resource = resourceFromAttributes({ })
     const memExporter = new InMemoryMetricExporter(AggregationTemporality.DELTA)

package/lib/otel/{logs/normalize-timestamp.js → normalize-timestamp.js}

@@ -42,12 +42,7 @@ function normalizeTimestamp(input) {
   }
 
   if (isTimeInputHrTime(input) === true) {
-    // It's unclear why upstream tries to support a `process.hrtime()` value.
-    // Such tuples are relative to an arbitrary point in time, not the Unix
-    // epoch. So there's no way to determine an actual wall clock time and date
-    // from such input. For lack of a better solution, we'll return the
-    // current epoch in this case.
-    return Date.now()
+    return hrtimeToMilliseconds(input)
   }
 
   if (Object.getPrototypeOf(input) === Date.prototype) {
@@ -57,3 +52,34 @@ function normalizeTimestamp(input) {
   // We don't know what they've given us, so just return the current time.
   return Date.now()
 }
+
+/**
+ * Converts a JS Open Telemetry hrtime tuple to milliseconds since the
+ * standard epoch. The OTEL hrtime is created as follows:
+ *
+ * 1. Convert `performance.timeOrigin` to a `[seconds, nanoseconds]` tuple.
+ * 2. Add the result of `performance.now()` to the tuple to adjust to the
+ * current time.
+ *
+ * Thus, the tuple represents a literal point in time that, when converted
+ * back to a single integer, can be passed to `new Date()` to get an accurate
+ * representation.
+ *
+ * @param {number[]} hrtime Upstream represents hrtime as `[seconds, nanoseconds]`.
+ *
+ * @returns {number} Milliseconds since standard epoch time.
+ */
+function hrtimeToMilliseconds(hrtime) {
+  const seconds = hrtime[0]
+  const nanoseconds = hrtime[1]
+
+  // Convert the seconds portion to milliseconds.
+  const msSeconds = seconds * 1_000
+  // Convert the nanoseconds portion to milliseconds.
+  const msNanoseconds = nanoseconds / 1_000_000
+  // At this point, we have the number of milliseconds since the standard
+  // epoch.
+  const msSinceEpoch = msSeconds + msNanoseconds
+
+  return Math.trunc(msSinceEpoch)
+}

package/lib/otel/setup.js

@@ -19,9 +19,9 @@ const interceptSpanKey = require('./span-key-interceptor')
 const signals = []
 
 function setupOtel(agent, logger = defaultLogger) {
-  if (agent.config.opentelemetry_bridge.enabled !== true) {
+  if (agent.config.opentelemetry.enabled !== true) {
     logger.warn(
-      '`opentelemetry_bridge` is not enabled, skipping setup of opentelemetry-bridge'
+      '`opentelemetry` is not enabled, skipping setup of opentelemetry'
     )
     return
   }
@@ -36,31 +36,31 @@ function setupOtel(agent, logger = defaultLogger) {
   opentelemetry.context.setGlobalContextManager(new ContextManager(agent))
   opentelemetry.propagation.setGlobalPropagator(new TracePropagator(agent))
 
-  if (agent.config.opentelemetry_bridge.traces.enabled === true) {
+  if (agent.config.opentelemetry.traces.enabled === true) {
     const signal = new SetupTraces({ agent })
     signals.push(signal)
   } else {
-    logger.debug('`opentelemetry_bridge.traces` is not enabled, skipping')
+    logger.debug('`opentelemetry.traces` is not enabled, skipping')
     agent.metrics
       .getOrCreateMetric('Supportability/Tracing/Nodejs/OpenTelemetryBridge/disabled')
       .incrementCallCount()
   }
 
-  if (agent.config.opentelemetry_bridge.metrics.enabled === true) {
+  if (agent.config.opentelemetry.metrics.enabled === true) {
     const signal = new SetupMetrics({ agent })
     signals.push(signal)
   } else {
-    logger.debug('`opentelemetry_bridge.metrics` is not enabled, skipping')
+    logger.debug('`opentelemetry.metrics` is not enabled, skipping')
     agent.metrics
       .getOrCreateMetric('Supportability/Metrics/Nodejs/OpenTelemetryBridge/disabled')
       .incrementCallCount()
   }
 
-  if (agent.config.opentelemetry_bridge.logs.enabled === true) {
+  if (agent.config.opentelemetry.logs.enabled === true) {
     const signal = new SetupLogs({ agent })
     signals.push(signal)
   } else {
-    logger.debug('`opentelemetry_bridge.logs` is not enabled, skipping')
+    logger.debug('`opentelemetry.logs` is not enabled, skipping')
   }
 
   agent.metrics
@@ -69,7 +69,7 @@ function setupOtel(agent, logger = defaultLogger) {
 }
 
 function teardownOtel(agent) {
-  if (agent?.config?.opentelemetry_bridge?.enabled !== true) {
+  if (agent?.config?.opentelemetry?.enabled !== true) {
     return
   }
 

package/lib/otel/traces/segment-synthesis.js

@@ -6,6 +6,8 @@
 'use strict'
 
 const defaultLogger = require('#agentlib/logger.js').child({ component: 'segment-synthesizer' })
+const SpanLink = require('#agentlib/spans/span-link.js')
+const normalizeTimestamp = require('../normalize-timestamp.js')
 const { RulesEngine } = require('./rules.js')
 const {
   createConsumerSegment,
@@ -34,35 +36,57 @@ class SegmentSynthesizer {
       return
     }
 
+    let mapResult
     switch (rule.type) {
       case 'consumer': {
-        return createConsumerSegment(this.agent, otelSpan, rule)
+        mapResult = createConsumerSegment(this.agent, otelSpan, rule)
+        break
       }
 
       case 'db': {
-        return createDbSegment(this.agent, otelSpan, rule)
+        mapResult = createDbSegment(this.agent, otelSpan, rule)
+        break
       }
 
       case 'external': {
-        return createHttpExternalSegment(this.agent, otelSpan, rule, this.logger)
+        mapResult = createHttpExternalSegment(this.agent, otelSpan, rule, this.logger)
+        break
       }
 
       case 'internal': {
-        return createInternalSegment(this.agent, otelSpan, rule)
+        mapResult = createInternalSegment(this.agent, otelSpan, rule)
+        break
       }
 
       case 'producer': {
-        return createProducerSegment(this.agent, otelSpan, rule)
+        mapResult = createProducerSegment(this.agent, otelSpan, rule)
+        break
       }
 
       case 'server': {
-        return createServerSegment(this.agent, otelSpan, rule)
+        mapResult = createServerSegment(this.agent, otelSpan, rule)
+        break
       }
 
       default: {
         this.logger.debug('Found type: %s, no synthesis rule currently built', rule.type)
+        return
       }
     }
+
+    if (otelSpan.links?.length > 0) {
+      // We need to map span link data over to the New Relic segment.
+      for (let i = 0; i < otelSpan.links.length; i += 1) {
+        const link = new SpanLink({
+          link: otelSpan.links.at(i),
+          spanContext: otelSpan.spanContext(),
+          timestamp: normalizeTimestamp(otelSpan.startTime)
+        })
+        mapResult.segment.addSpanLink(link)
+      }
+    }
+
+    return mapResult
   }
 }
 

package/lib/otel/traces/segments/index.js

@@ -8,9 +8,9 @@
 const createConsumerSegment = require('./consumer.js')
 const createDbSegment = require('./database.js')
 const createHttpExternalSegment = require('./http-external.js')
+const createInternalSegment = require('./internal.js')
 const createProducerSegment = require('./producer.js')
 const createServerSegment = require('./server.js')
-const createInternalSegment = require('./internal.js')
 
 module.exports = {
   createConsumerSegment,

package/lib/otel/traces/span-processor.js

@@ -45,12 +45,26 @@ module.exports = class NrSpanProcessor {
 
   /**
    * Update the segment duration from span, handle errors and
-   * map and reconcile any attributes that were to span.
+   * map and reconcile any attributes that were added to the span.
    * @param {object} span otel span getting updated
    */
   onEnd(span) {
     if (span[otelSynthesis] && span[otelSynthesis].segment) {
       const { segment, transaction, rule } = span[otelSynthesis]
+      const { instrumentationScope } = span
+
+      // We always attach the instrumentation scope data as agent attributes
+      // if the OTEL span has them set.
+      // See https://opentelemetry.io/docs/specs/otel/common/mapping-to-non-otlp/#instrumentationscope
+      if (typeof instrumentationScope.name === 'string') {
+        segment.addAttribute('otel.scope.name', instrumentationScope.name)
+        segment.addAttribute('otel.library.name', instrumentationScope.name)
+      }
+      if (typeof instrumentationScope.version === 'string') {
+        segment.addAttribute('otel.scope.version', instrumentationScope.version)
+        segment.addAttribute('otel.library.version', instrumentationScope.version)
+      }
+
       this.updateDuration(segment, span)
       this.handleError({ segment, transaction, span })
       this.reconcileAttributes({ segment, span, transaction, rule })

package/lib/otel/traces/utils.js

@@ -22,7 +22,9 @@ function transformTemplate(template, data, rules = {}) {
       if (key in rules) {
         return rules[key](data[key])
       } else {
-        return data[key] ?? 'unknown'
+        // We use || here instead of ?? because we could be comparing against
+        // an empty string, not `null` or `undefined`.
+        return data[key] || 'unknown'
       }
     } else {
       return 'unknown'

package/lib/samplers/README.md

@@ -0,0 +1,79 @@
+# Sampling at New Relic
+
+The New Relic agent supports a robust sampling decision making interface. This is a work-in-progress feature.
+
+## 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`, `distributed_tracing.sampler.full_granularity.enabled = true`, and if they want partial granularity traces, `distributed_tracing.sampler.partial_granularity.enabled = true`.
+
+### Types
+
+- A "sampler mode" refers to the following config sections: `distributed_tracing.sampler` and `distributed_tracing.sampler.partial_granularity`. They are defined by the three sections: `root`, `remote_parent_sampled`, and `remote_parent_not_sampled`.
+- A "sampler section" refers to `root`, `remote_parent_sampled`, or `remote_parent_not_sampled` within a particular sampler mode. The config defined at this section, i.e. `SAMPLER_TYPE: SAMPLER_SUBOPTION?`, describes the sampling decision for that particular scenario within that mode.
+  - `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
+...
+(Serverless DT attributes; they may be defined under distributed_tracing instead)
+account_id: string (unset by default, only set when using Serverless Mode)
+trusted_account_key: string (unset by default, only set when using Serverless Mode)
+primary_application_id: string (unset by default, only set when using Serverless Mode)
+...
+distributed_tracing:
+  enabled: boolean (default true)
+  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 above)
+    root: (when the trace originates from the current service)
+      ${SAMPLER_TYPE} (See `Sampler Options` above)
+        ${SAMPLER_SUBOPTION}
+    remote_parent_sampled: (when the upstream service has sampled the trace)
+      ${SAMPLER_TYPE})
+        ${SAMPLER_SUBOPTION}
+    remote_parent_not_sampled: (when the upstream service has not sampled the trace)
+      ${SAMPLER_TYPE}
+        ${SAMPLER_SUBOPTION}
+    full_granularity:
+      enabled
+    partial_granularity:
+      enabled
+      type   ("reduced", "essential", "compact")
+      root: (when the trace originates from the current service)
+        ${SAMPLER_TYPE}
+          ${SAMPLER_SUBOPTION}
+      remote_parent_sampled: (when the upstream service has sampled the trace)
+        ${SAMPLER_TYPE}
+          ${SAMPLER_SUBOPTION}
+      remote_parent_not_sampled: (when the upstream service has not sampled the trace)
+        ${SAMPLER_TYPE}
+          ${SAMPLER_SUBOPTION}
+...
+```
+
+## Solution
+
+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.samplers` is defined as:
+
+* `agent.samplers.root`
+* `agent.samplers.remoteParentSampled`
+* `agent.samplers.remoteParentNotSampled`
+* `agent.samplers.partialRoot`
+* `agent.samplers.partialRemoteParentSampled`
+* `agent.samplers.partialRemoteParentNotSampled`
+* `agent.samplers.adaptiveSampler` (if needed, see below)
+
+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 `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.

package/lib/samplers/adaptive-sampler.js

@@ -5,7 +5,9 @@
 
 'use strict'
 
-class AdaptiveSampler {
+const Sampler = require('./sampler')
+
+class AdaptiveSampler extends Sampler {
   /**
    *
    * @param {object} opts Sampler options.
@@ -15,12 +17,16 @@ class AdaptiveSampler {
    * @param {boolean} opts.serverless - Indicates if the environment is serverless.
    */
   constructor(opts) {
+    super() // no-op
     this._serverless = opts.serverless
     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
@@ -99,6 +105,24 @@ class AdaptiveSampler {
     return false
   }
 
+  applySamplingDecision({ transaction, tracestate, partialType }) {
+    if (!transaction) return
+    transaction.partialType = partialType
+    if (tracestate) {
+      // Explicitly set sampled and priority from tracestate intrinsics if available
+      transaction.sampled = tracestate?.intrinsics ? tracestate.isSampled : null
+      transaction.priority = tracestate?.intrinsics ? tracestate.priority : null
+      return
+    }
+
+    // If a tracestate is not defined, then do our normal priority calculation.
+
+    const initPriority = Sampler.generatePriority()
+    transaction.sampled = this.shouldSample(initPriority)
+    // only add 1 to priority when doing a full trace
+    transaction.priority = transaction.sampled && !partialType ? Sampler.incrementPriority(initPriority, 1) : initPriority
+  }
+
   /**
    * Starts a new sample period after adjusting the sampling statistics.
    */