dd-trace 5.96.0 → 5.97.0

package/packages/dd-trace/src/profiling/profilers/wall.js

@@ -108,6 +108,8 @@ class NativeWallProfiler {
   #captureSpanData = false
   #codeHotspotsEnabled = false
   #cpuProfilingEnabled = false
+  #customLabelsActive = false
+  #customLabelKeys
   #endpointCollectionEnabled = false
   #flushIntervalMillis = 0
   #logger
@@ -245,7 +247,24 @@ class NativeWallProfiler {
     // context -- we simply can't tell which one it might've been across all
     // possible async context frames.
     if (this.#asyncContextFrameEnabled) {
-      this.#pprof.time.setContext(sampleContext)
+      if (this.#customLabelsActive) {
+        // Custom labels may be active in this async context. The current CPED
+        // context could be a 2-element array [profilingContext, customLabels].
+        // Replace the profiling context while preserving the custom labels.
+        // This flag is monotonic (once set, stays true) because async
+        // continuations from runWithLabels can fire at any time after the
+        // synchronous runWithLabels call has returned.
+        const current = this.#pprof.time.getContext()
+        if (Array.isArray(current)) {
+          if (current[0] !== sampleContext) {
+            this.#pprof.time.setContext([sampleContext, current[1]])
+          }
+        } else if (current !== sampleContext) {
+          this.#pprof.time.setContext(sampleContext)
+        }
+      } else {
+        this.#pprof.time.setContext(sampleContext)
+      }
     } else {
       const sampleCount = this._profilerState[kSampleCount]
       if (sampleCount !== this._lastSampleCount) {
@@ -344,6 +363,13 @@ class NativeWallProfiler {
     const lowCardinalityLabels = Object.keys(getThreadLabels())
     lowCardinalityLabels.push(TRACE_ENDPOINT_LABEL)
 
+    // Custom labels are expected to be low-cardinality (e.g. customer tier, region)
+    if (this.#customLabelKeys) {
+      for (const key of this.#customLabelKeys) {
+        lowCardinalityLabels.push(key)
+      }
+    }
+
     const profile = this.#pprof.time.stop(restart, this.#boundGenerateLabels, lowCardinalityLabels)
 
     if (restart) {
@@ -383,7 +409,29 @@ class NativeWallProfiler {
       return getThreadLabels()
     }
 
-    const labels = { ...getThreadLabels() }
+    // Native profiler doesn't set context.context for some samples, such as idle samples or when
+    // the context was otherwise unavailable when the sample was taken. Note that with ACF, we don't
+    // use the "ref" indirection.
+    let ref
+    let customLabels
+    const cctx = context.context
+    if (this.#asyncContextFrameEnabled) {
+      // When custom labels are active with ACF, context.context is a 2-element array:
+      // [profilingContext, customLabels]. Otherwise it's a plain object.
+      if (Array.isArray(cctx)) {
+        [ref, customLabels] = cctx
+      } else {
+        ref = cctx
+      }
+    } else {
+      ref = cctx?.ref
+    }
+
+    // Custom labels are spread first so that internal labels always take
+    // precedence and overwrite them.
+    const labels = customLabels === undefined
+      ? { ...getThreadLabels() }
+      : { ...customLabels, ...getThreadLabels() }
 
     if (this.#timelineEnabled) {
       // Incoming timestamps are in microseconds, we emit nanos.
@@ -395,10 +443,6 @@ class NativeWallProfiler {
       labels['async id'] = asyncId
     }
 
-    // Native profiler doesn't set context.context for some samples, such as idle samples or when
-    // the context was otherwise unavailable when the sample was taken. Note that with async context
-    // frame, we don't use the "ref" indirection.
-    const ref = this.#asyncContextFrameEnabled ? context.context : context.context?.ref
     if (typeof ref !== 'object') {
       return labels
     }
@@ -421,6 +465,45 @@ class NativeWallProfiler {
     return labels
   }
 
+  /**
+   * Sets the custom label keys used for pprof low-cardinality deduplication.
+   * Called once by the top-level Profiler when keys are declared.
+   *
+   * @param {Iterable<string>} keys
+   */
+  setCustomLabelKeys (keys) {
+    this.#customLabelKeys = keys
+  }
+
+  /**
+   * Runs a function with custom profiling labels attached to all wall profiler
+   * samples taken during its execution. Labels are key-value pairs that appear
+   * in the pprof output and can be used to filter flame graphs in the Datadog UI.
+   *
+   * Requires AsyncContextFrame (ACF) to be enabled. Supports nesting: inner
+   * calls merge labels with outer calls, with inner values taking precedence.
+   *
+   * @param {Record<string, string | number>} labels - Custom labels to attach
+   * @param {function(): T} fn - Function to execute with the labels
+   * @returns {T} The return value of fn
+   * @template T
+   */
+  runWithLabels (labels, fn) {
+    if (!this.#asyncContextFrameEnabled || !this.#withContexts) {
+      return fn()
+    }
+
+    // Read current context; merge custom labels if already in a runWithLabels scope
+    const current = this.#pprof.time.getContext()
+    const isCurrentArray = Array.isArray(current)
+    const customLabels = isCurrentArray ? { ...current[1], ...labels } : labels
+
+    const profilingContext = (isCurrentArray ? current[0] : current) ?? {}
+
+    this.#customLabelsActive = true
+    return this.#pprof.time.runWithContext([profilingContext, customLabels], fn)
+  }
+
   profile (restart) {
     return this.#stop(restart)
   }

package/packages/dd-trace/src/profiling/ssi-heuristics.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const dc = require('dc-polyfill')
+const dc = /** @type {typeof import('diagnostics_channel')} */ (require('dc-polyfill'))
 const log = require('../log')
 
 // If the process lives for at least 30 seconds, it's considered long-lived
@@ -10,6 +10,9 @@ const DEFAULT_LONG_LIVED_THRESHOLD = 30_000
  * This class embodies the SSI profiler-triggering heuristics under SSI.
  */
 class SSIHeuristics {
+  /**
+   * @param {import('../config/config-base')} config - Tracer configuration
+   */
   constructor (config) {
     const longLivedThreshold = config.profiling.longLivedThreshold || DEFAULT_LONG_LIVED_THRESHOLD
     if (typeof longLivedThreshold !== 'number' || longLivedThreshold <= 0) {

package/packages/dd-trace/src/propagation-hash/index.js

@@ -17,11 +17,12 @@ class PropagationHashManager {
   _cachedHash = null
   _cachedHashString = null
   _cachedHashBase64 = null
+  /** @type {import('../config/config-base') | null} */
   _config = null
 
   /**
    * Configure the propagation hash manager with tracer config
-   * @param {object} config - Tracer configuration
+   * @param {import('../config/config-base')} config - Tracer configuration
    */
   configure (config) {
     this._config = config

package/packages/dd-trace/src/proxy.js

@@ -27,9 +27,12 @@ class LazyModule {
     this.provider = provider
   }
 
-  enable (...args) {
+  /**
+   * @param {import('./config/config-base')} config - Tracer configuration
+   */
+  enable (config, ...args) {
     this.module = this.provider()
-    this.module.enable(...args)
+    this.module.enable(config, ...args)
   }
 
   disable () {
@@ -238,12 +241,16 @@ class Tracer extends NoopProxy {
         getDynamicInstrumentationClient(config)
       }
     } catch (e) {
-      log.error('Error initialising tracer', e)
+      log.error('Error initializing tracer', e)
+      // TODO: Should we stop everything started so far?
     }
 
     return this
   }
 
+  /**
+   * @param {import('./config/config-base')} config - Tracer configuration
+   */
   _startProfiler (config) {
     // do not stop tracer initialization if the profiler fails to be imported
     try {
@@ -257,6 +264,9 @@ class Tracer extends NoopProxy {
     }
   }
 
+  /**
+   * @param {import('./config/config-base')} config - Tracer configuration
+   */
   #updateTracing (config) {
     if (config.tracing !== false) {
       if (config.appsec.enabled) {
@@ -330,6 +340,25 @@ class Tracer extends NoopProxy {
     }
   }
 
+  /**
+   * @override
+   */
+  get profiling () {
+    // Lazily require the profiler module and cache the result. If profiling
+    // is not enabled, runWithLabels still works as a passthrough (just calls fn()).
+    const profilerModule = require('./profiler')
+    const profiling = {
+      setCustomLabelKeys (keys) {
+        profilerModule.setCustomLabelKeys(keys)
+      },
+      runWithLabels (labels, fn) {
+        return profilerModule.runWithLabels(labels, fn)
+      },
+    }
+    Reflect.defineProperty(this, 'profiling', { value: profiling, configurable: true, enumerable: true })
+    return profiling
+  }
+
   /**
    * @override
    */

package/packages/dd-trace/src/remote_config/index.js

@@ -25,6 +25,9 @@ class RemoteConfig {
   #products = new Set()
   #batchHandlers = new Map()
 
+  /**
+   * @param {import('../config/config-base')} config - Tracer configuration
+   */
   constructor (config) {
     const pollInterval = Math.floor(config.remoteConfig.pollInterval * 1000)
 

package/packages/dd-trace/src/require-package-json.js

@@ -21,10 +21,14 @@ function requirePackageJson (name, module) {
   }
   for (const modulePath of module.paths) {
     const candidate = path.join(modulePath, name, 'package.json')
-    try {
-      return JSON.parse(fs.readFileSync(candidate, 'utf8'))
-    } catch {
-      continue
+    // fs.existsSync is faster than fs.readFileSync due to not throwing an error if the file does not exist.
+    // The race condition should also not matter here as the time window is very small.
+    if (fs.existsSync(candidate)) {
+      try {
+        return JSON.parse(fs.readFileSync(candidate, 'utf8'))
+      } catch {
+        continue
+      }
     }
   }
   throw new Error(`could not find ${name}/package.json`)

package/packages/dd-trace/src/ritm.js

@@ -22,19 +22,44 @@ let patchedRequire = null
 const moduleLoadStartChannel = dc.channel('dd-trace:moduleLoadStart')
 const moduleLoadEndChannel = dc.channel('dd-trace:moduleLoadEnd')
 
+function stripNodePrefix (name) {
+  if (typeof name !== 'string') return name
+  return name.startsWith('node:') ? name.slice(5) : name
+}
+
+const builtinModules = new Set(Module.builtinModules.map(stripNodePrefix))
+
+function isBuiltinModuleName (name) {
+  if (typeof name !== 'string') return false
+  return builtinModules.has(stripNodePrefix(name))
+}
+
+function normalizeModuleName (name) {
+  if (typeof name !== 'string') return name
+  const stripped = stripNodePrefix(name)
+  return builtinModules.has(stripped) ? stripped : name
+}
+
+/**
+ * @overload
+ * @param {string[]} modules list of modules to hook into
+ * @param {object} options hook options
+ * @param {Function} onrequire callback to be executed upon encountering module
+ */
+/**
+ * @overload
+ * @param {string[]} modules list of modules to hook into
+ * @param {Function} onrequire callback to be executed upon encountering module
+ */
 function Hook (modules, options, onrequire) {
   if (!(this instanceof Hook)) return new Hook(modules, options, onrequire)
-  if (typeof modules === 'function') {
-    onrequire = modules
-    modules = null
-    options = {}
-  } else if (typeof options === 'function') {
+  if (typeof options === 'function') {
     onrequire = options
     options = {}
   }
 
-  modules = modules || []
-  options = options || {}
+  modules ??= []
+  options ??= {}
 
   this.modules = modules
   this.options = options
@@ -63,32 +88,34 @@ function Hook (modules, options, onrequire) {
     */
     let filename
     try {
-      // @ts-expect-error Module._resolveFilename is not typed
+      // @ts-expect-error - Module._resolveFilename is not typed
       filename = Module._resolveFilename(request, this)
     } catch {
       return _origRequire.apply(this, arguments)
     }
-    const core = !filename.includes(path.sep)
+
+    const builtin = isBuiltinModuleName(filename)
+    const moduleId = builtin ? normalizeModuleName(filename) : filename
     let name, basedir, hooks
     // return known patched modules immediately
-    if (cache[filename]) {
-      const externalCacheEntry = require.cache[filename]
+    if (cache[moduleId]) {
       // require.cache was potentially altered externally
-      if (externalCacheEntry && externalCacheEntry.exports !== cache[filename].original) {
-        return externalCacheEntry.exports
+      const cacheEntry = require.cache[filename]
+      if (cacheEntry && cacheEntry.exports !== cache[filename].original) {
+        return cacheEntry.exports
       }
 
-      return cache[filename].exports
+      return cache[moduleId].exports
     }
 
     // Check if this module has a patcher in-progress already.
     // Otherwise, mark this module as patching in-progress.
-    const patched = patching[filename]
+    const patched = patching[moduleId]
     if (patched) {
       // If it's already patched, just return it as-is.
       return origRequire.apply(this, arguments)
     }
-    patching[filename] = true
+    patching[moduleId] = true
 
     const payload = {
       filename,
@@ -107,12 +134,12 @@ function Hook (modules, options, onrequire) {
 
     // The module has already been loaded,
     // so the patching mark can be cleaned up.
-    delete patching[filename]
+    delete patching[moduleId]
 
-    if (core) {
-      hooks = moduleHooks[filename]
+    if (builtin) {
+      hooks = moduleHooks[moduleId]
       if (!hooks) return exports // abort if module name isn't on whitelist
-      name = filename
+      name = moduleId
     } else {
       const inAWSLambda = getEnvironmentVariable('AWS_LAMBDA_FUNCTION_NAME') !== undefined
       const hasLambdaHandler = getValueFromEnvSources('DD_LAMBDA_HANDLER') !== undefined
@@ -129,7 +156,8 @@ function Hook (modules, options, onrequire) {
         hooks = moduleHooks[name]
         if (!hooks) return exports // abort if module name isn't on whitelist
 
-        // @ts-expect-error Module._resolveLookupPaths is not typed
+        // figure out if this is the main module file, or a file inside the module
+        // @ts-expect-error - Module._resolveLookupPaths is meant to be internal and is not typed
         const paths = Module._resolveLookupPaths(name, this, true)
         if (!paths) {
           // abort if _resolveLookupPaths return null
@@ -138,7 +166,7 @@ function Hook (modules, options, onrequire) {
 
         let res
         try {
-          // @ts-expect-error Module._findPath is not typed
+          // @ts-expect-error - Module._findPath is meant to be internal and is not typed
           res = Module._findPath(name, [basedir, ...paths])
         } catch {
           // case where the file specified in package.json "main" doesn't exist
@@ -163,17 +191,21 @@ function Hook (modules, options, onrequire) {
 
     // ensure that the cache entry is assigned a value before calling
     // onrequire, in case calling onrequire requires the same module.
-    cache[filename] = { exports }
-    cache[filename].original = exports
+    cache[moduleId] = { exports }
+    cache[moduleId].original = exports
 
     for (const hook of hooks) {
-      cache[filename].exports = hook(cache[filename].exports, name, basedir)
+      cache[moduleId].exports = hook(cache[moduleId].exports, name, basedir)
     }
 
-    return cache[filename].exports
+    return cache[moduleId].exports
   }
 }
 
+/**
+ * Reset the Ritm hook. This is used to reset the hook after a test.
+ * TODO: Remove this and instead use proxyquire to reset the hook.
+ */
 Hook.reset = function () {
   Module.prototype.require = origRequire
   patchedRequire = null

package/packages/dd-trace/src/runtime_metrics/index.js

@@ -14,6 +14,9 @@ const noop = runtimeMetrics = {
 }
 
 module.exports = {
+  /**
+   * @param {import('../config/config-base')} config - Tracer configuration
+   */
   start (config) {
     if (!config?.runtimeMetrics.enabled) return
 

package/packages/dd-trace/src/runtime_metrics/runtime_metrics.js

@@ -35,6 +35,9 @@ let eventLoopDelayObserver = null
 // https://github.com/DataDog/dogweb/blob/prod/integration/node/node_metadata.csv
 
 module.exports = {
+  /**
+   * @param {import('../config/config-base')} config - Tracer configuration
+   */
   start (config) {
     this.stop()
     const clientConfig = DogStatsDClient.generateClientConfig(config)

package/packages/dd-trace/src/sampler.js

@@ -42,7 +42,7 @@ class Sampler {
   /**
    * Determines whether a trace/span should be sampled based on the configured sampling rate.
    *
-   * @param {Span|SpanContext} span - The span or span context to evaluate.
+   * @param {import("../../..").Span|import("../../..").SpanContext} span - The span or span context to evaluate.
    * @returns {boolean} `true` if the trace/span should be sampled, otherwise `false`.
    */
   isSampled (span) {

package/packages/dd-trace/src/standalone/index.js

@@ -11,6 +11,9 @@ const startCh = channel('dd-trace:span:start')
 const injectCh = channel('dd-trace:span:inject')
 const extractCh = channel('dd-trace:span:extract')
 
+/**
+ * @param {import('../config/config-base')} config - Tracer configuration
+ */
 function configure (config) {
   if (startCh.hasSubscribers) startCh.unsubscribe(onSpanStart)
   if (injectCh.hasSubscribers) injectCh.unsubscribe(onSpanInject)

package/packages/dd-trace/src/telemetry/index.js

@@ -5,15 +5,14 @@ let telemetry
 // Lazy load the telemetry module to avoid the performance impact of loading it unconditionally
 module.exports = {
   start (config, ...args) {
+    if (!config.telemetry.enabled) return
     telemetry ??= require('./telemetry')
     telemetry.start(config, ...args)
   },
-  stop () {
-    telemetry?.stop()
-  },
   // This might be called before `start` so we have to trigger loading the
   // underlying module here as well.
   updateConfig (changes, config, ...args) {
+    if (!config.telemetry.enabled) return
     telemetry ??= require('./telemetry')
     telemetry.updateConfig(changes, config, ...args)
   },

package/packages/dd-trace/src/telemetry/send-data.js

@@ -62,19 +62,6 @@ const { getValueFromEnvSources } = require('../config/helper')
  *   kernel_name?: string
  * } & Record<string, unknown>} TelemetryHost
  */
-/**
- * @typedef {{
- *   hostname?: string,
- *   port?: string | number,
- *   url?: string | URL,
- *   site?: string,
- *   apiKey?: string,
- *   isCiVisibility?: boolean,
- *   spanAttributeSchema?: string,
- *   tags: Record<string, string>,
- *   telemetry?: { debug?: boolean }
- * }} TelemetryConfig
- */
 /**
  * @callback SendDataCallback
  * @param {Error | null | undefined} error
@@ -85,23 +72,22 @@ const { getValueFromEnvSources } = require('../config/helper')
 let agentTelemetry = true
 
 /**
- * @param {TelemetryConfig} config
+ * @param {import('../config/config-base')} config
  * @param {TelemetryApplication} application
  * @param {TelemetryRequestType} reqType
  * @returns {Record<string, string>}
  */
 function getHeaders (config, application, reqType) {
-  const sessionId = config.tags['runtime-id']
   const headers = {
     'content-type': 'application/json',
     'dd-telemetry-api-version': 'v2',
     'dd-telemetry-request-type': reqType,
     'dd-client-library-language': application.language_name,
     'dd-client-library-version': application.tracer_version,
-    'dd-session-id': sessionId,
+    'dd-session-id': config.tags['runtime-id'],
   }
-  if (config.rootSessionId && config.rootSessionId !== sessionId) {
-    headers['dd-root-session-id'] = config.rootSessionId
+  if (config.DD_ROOT_JS_SESSION_ID) {
+    headers['dd-root-session-id'] = config.DD_ROOT_JS_SESSION_ID
   }
   const debug = config.telemetry && config.telemetry.debug
   if (debug) {
@@ -141,7 +127,7 @@ function getPayload (payload) {
 
 // TODO(BridgeAR): Simplify this code. A lot does not need to be recalculated on every call.
 /**
- * @param {TelemetryConfig} config
+ * @param {import('../config/config-base')} config
  * @param {TelemetryApplication} application
  * @param {TelemetryHost} host
  * @param {TelemetryRequestType} reqType

package/packages/dd-trace/src/telemetry/session-propagation.js

@@ -1,53 +1,37 @@
 'use strict'
 
-const dc = require('dc-polyfill')
-
+const dc = /** @type {typeof import('diagnostics_channel')} */ (require('dc-polyfill'))
 const childProcessChannel = dc.tracingChannel('datadog:child_process:execution')
 
 let subscribed = false
-let rootSessionId
 let runtimeId
 
-function injectSessionEnv (existingEnv) {
-  // eslint-disable-next-line eslint-rules/eslint-process-env -- not in supported-configurations.json
-  const base = existingEnv == null ? process.env : existingEnv
-  return {
-    ...base,
-    DD_ROOT_JS_SESSION_ID: rootSessionId,
-    DD_PARENT_JS_SESSION_ID: runtimeId,
-  }
+function isOptionsObject (value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value) && value
 }
 
-function findOptionsIndex (args, shell) {
-  if (Array.isArray(args[1])) {
-    return { index: 2, exists: args[2] != null && typeof args[2] === 'object' }
-  }
-  if (args[1] != null && typeof args[1] === 'object') {
-    return { index: 1, exists: true }
-  }
-  if (!shell && args[2] != null && typeof args[2] === 'object') {
-    return { index: 2, exists: true }
-  }
-  return { index: shell ? 1 : 2, exists: false }
+function getEnvWithRuntimeId (env) {
+  // eslint-disable-next-line eslint-rules/eslint-process-env
+  return { ...(env ?? process.env), DD_ROOT_JS_SESSION_ID: runtimeId }
 }
 
 function onChildProcessStart (context) {
-  if (!context.callArgs) return
-
   const args = context.callArgs
-  const { index, exists } = findOptionsIndex(args, context.shell)
+  if (!args) return
 
-  if (exists) {
-    args[index] = { ...args[index], env: injectSessionEnv(args[index].env) }
+  const index = Array.isArray(args[1]) || (!context.shell && !isOptionsObject(args[1])) ? 2 : 1
+  const options = isOptionsObject(args[index]) ? args[index] : undefined
+
+  if (options) {
+    args[index] = { ...options, env: getEnvWithRuntimeId(options.env) }
     return
   }
 
-  const opts = { env: injectSessionEnv(null) }
-
-  if (!context.shell && !Array.isArray(args[1])) {
+  if (index === 2 && !Array.isArray(args[1])) {
     args.splice(1, 0, [])
   }
 
+  const opts = { env: getEnvWithRuntimeId() }
   if (typeof args[index] === 'function') {
     args.splice(index, 0, opts)
   } else {
@@ -55,24 +39,15 @@ function onChildProcessStart (context) {
   }
 }
 
-const handler = { start: onChildProcessStart }
-
 function start (config) {
   if (!config.telemetry?.enabled || subscribed) return
   subscribed = true
 
-  rootSessionId = config.rootSessionId
-  runtimeId = config.tags['runtime-id']
-
-  childProcessChannel.subscribe(handler)
-}
+  runtimeId = config.DD_ROOT_JS_SESSION_ID || config.tags['runtime-id']
 
-function stop () {
-  if (!subscribed) return
-  childProcessChannel.unsubscribe(handler)
-  subscribed = false
-  rootSessionId = undefined
-  runtimeId = undefined
+  childProcessChannel.subscribe(
+    /** @type {import('diagnostics_channel').TracingChannelSubscribers<object>} */ ({ start: onChildProcessStart })
+  )
 }
 
-module.exports = { start, stop, _onChildProcessStart: onChildProcessStart }
+module.exports = { start }