dd-trace 5.96.0 → 5.98.0

package/packages/dd-trace/src/profiling/exporters/event_serializer.js

@@ -14,7 +14,7 @@ class EventSerializer {
     this._host = host
     this._service = service
     this._appVersion = version
-    this._libraryInjected = !!libraryInjected
+    this._libraryInjected = libraryInjected
     this._activation = activation || 'unknown'
   }
 
@@ -22,7 +22,7 @@ class EventSerializer {
     return `${type}.pprof`
   }
 
-  getEventJSON ({ profiles, infos, start, end, tags = {}, endpointCounts }) {
+  getEventJSON ({ profiles, infos, start, end, tags = {}, endpointCounts, customAttributes }) {
     const event = {
       attachments: Object.keys(profiles).map(t => this.typeToFile(t)),
       start: start.toISOString(),
@@ -80,6 +80,10 @@ class EventSerializer {
       },
     }
 
+    if (customAttributes) {
+      event.custom_attributes = customAttributes
+    }
+
     if (processTags.serialized) {
       event[processTags.PROFILING_FIELD_NAME] = processTags.serialized
     }

package/packages/dd-trace/src/profiling/profiler.js

@@ -12,12 +12,6 @@ const { isWebServerSpan, endpointNameFromTags, getStartedSpans } = require('./we
 const profileSubmittedChannel = dc.channel('datadog:profiling:profile-submitted')
 const spanFinishedChannel = dc.channel('dd-trace:span:finish')
 
-function logError (logger, ...args) {
-  if (logger) {
-    logger.error(...args)
-  }
-}
-
 function findWebSpan (startedSpans, spanId) {
   for (let i = startedSpans.length; --i >= 0;) {
     const ispan = startedSpans[i]
@@ -51,6 +45,7 @@ class Profiler extends EventEmitter {
   #compressionFnInitialized = false
   #compressionOptions
   #config
+  #customLabelKeys = new Set()
   #enabled = false
   #endpointCounts = new Map()
   #lastStart
@@ -70,73 +65,47 @@ class Profiler extends EventEmitter {
     return this.#config?.flushInterval
   }
 
-  start (config) {
-    const {
-      service,
-      version,
-      env,
-      url,
-      hostname,
-      port,
-      tags,
-      repositoryUrl,
-      commitSHA,
-      injectionEnabled,
-      reportHostname,
-    } = config
-    const { enabled, sourceMap, exporters } = config.profiling
-    const { heartbeatInterval } = config.telemetry
-
-    // TODO: Unify with main logger and rewrite template strings to use printf formatting.
-    const logger = {
-      debug (message) { log.debug(message) },
-      info (message) { log.info(message) },
-      warn (message) { log.warn(message) },
-      error (...args) { log.error(...args) },
-    }
+  get enabled () {
+    return this.#enabled
+  }
 
-    const libraryInjected = injectionEnabled.length > 0
-    let activation
-    if (enabled === 'auto') {
-      activation = 'auto'
-    } else if (enabled === 'true') {
-      activation = 'manual'
-    } // else activation = undefined
-
-    const options = {
-      service,
-      version,
-      env,
-      logger,
-      sourceMap,
-      exporters,
-      url,
-      hostname,
-      port,
-      tags,
-      repositoryUrl,
-      commitSHA,
-      libraryInjected,
-      activation,
-      heartbeatInterval,
-      reportHostname,
+  /**
+   * Declares the set of custom label keys that will be used with
+   * {@link runWithLabels}. This is used for profile upload metadata and
+   * for pprof serialization optimization (low-cardinality deduplication).
+   *
+   * @param {Iterable<string>} keys - Custom label key names
+   */
+  setCustomLabelKeys (keys) {
+    this.#customLabelKeys.clear()
+    for (const key of keys) {
+      this.#customLabelKeys.add(key)
     }
-
-    try {
-      return this._start(options)
-    } catch (err) {
-      logError(logger, 'Error starting profiler. For troubleshooting tips, see ' +
-        '<https://dtdg.co/nodejs-profiler-troubleshooting>', err)
-      return false
+    if (this.#config) {
+      for (const profiler of this.#config.profilers) {
+        profiler.setCustomLabelKeys?.(this.#customLabelKeys)
+      }
     }
   }
 
-  get enabled () {
-    return this.#enabled
-  }
-
-  #logError (err) {
-    logError(this.#logger, err)
+  /**
+   * Runs a function with custom profiling labels attached to wall profiler samples.
+   *
+   * @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.#enabled || !this.#config) {
+      return fn()
+    }
+    for (const profiler of this.#config.profilers) {
+      if (profiler.runWithLabels) {
+        return profiler.runWithLabels(labels, fn)
+      }
+    }
+    return fn()
   }
 
   #getCompressionFn () {
@@ -175,48 +144,46 @@ class Profiler extends EventEmitter {
             }
             break
         }
-      } catch (err) {
-        this.#logError(err)
+      } catch (error) {
+        log.error(error)
       }
     }
     return this.#compressionFn
   }
 
-  _start (options) {
+  /**
+   * @param {import('../config/config-base')} options - Tracer configuration
+   */
+  start (options) {
     if (this.enabled) return true
+    this.#enabled = true
 
     const config = this.#config = new Config(options)
-
     this.#logger = config.logger
-    this.#enabled = true
-    this._setInterval()
 
+    this._setInterval()
     // Log errors if the source map finder fails, but don't prevent the rest
     // of the profiler from running without source maps.
     let mapper
-    try {
-      const { setLogger, SourceMapper } = require('@datadog/pprof')
-      setLogger(config.logger)
-
-      if (config.sourceMap) {
-        mapper = new SourceMapper(config.debugSourceMaps)
-        mapper.loadDirectory(process.cwd())
-          .then(() => {
-            if (config.debugSourceMaps) {
-              const count = mapper.infoMap.size
-              this.#logger.debug(() => {
-                return count === 0
-                  ? 'Found no source maps'
-                  : `Found source maps for following files: [${[...mapper.infoMap.keys()].join(', ')}]`
-              })
-            }
-          })
-          .catch((err) => {
-            this.#logError(err)
-          })
-      }
-    } catch (err) {
-      this.#logError(err)
+    const { setLogger, SourceMapper } = require('@datadog/pprof')
+    setLogger(config.logger)
+
+    if (config.sourceMap) {
+      mapper = new SourceMapper(config.debugSourceMaps)
+      mapper.loadDirectory(process.cwd())
+        .then(() => {
+          if (config.debugSourceMaps) {
+            const count = mapper.infoMap.size
+            this.#logger.debug(() => {
+              return count === 0
+                ? 'Found no source maps'
+                : `Found source maps for following files: [${[...mapper.infoMap.keys()].join(', ')}]`
+            })
+          }
+        })
+        .catch((error) => {
+          log.error(error)
+        })
     }
 
     try {
@@ -237,12 +204,13 @@ class Profiler extends EventEmitter {
       }
 
       this._capture(this._timeoutInterval, start)
-      return true
-    } catch (e) {
-      this.#logError(e)
+    } catch (error) {
+      log.error(error)
       this.#stop()
       return false
     }
+
+    return true
   }
 
   #nearOOMExport (profileType, encodedProfile, info) {
@@ -380,10 +348,10 @@ class Profiler extends EventEmitter {
             return `Collected ${profiler.type} profile: ` + profileJson
           })
           hasEncoded = true
-        } catch (err) {
+        } catch (error) {
           // If encoding one of the profile types fails, we should still try to
           // encode and submit the other profile types.
-          this.#logError(err)
+          log.error(error)
         }
       }))
 
@@ -392,8 +360,8 @@ class Profiler extends EventEmitter {
         profileSubmittedChannel.publish()
         this.#logger.debug('Submitted profiles')
       }
-    } catch (err) {
-      this.#logError(err)
+    } catch (error) {
+      log.error(error)
       this.#stop()
     }
   }
@@ -410,12 +378,13 @@ class Profiler extends EventEmitter {
 
     tags.snapshot = snapshotKind
     tags.profile_seq = this.#profileSeq++
-    const exportSpec = { profiles, infos, start, end, tags, endpointCounts }
+    const customAttributes = this.#customLabelKeys.size > 0
+      ? [...this.#customLabelKeys]
+      : undefined
+    const exportSpec = { profiles, infos, start, end, tags, endpointCounts, customAttributes }
     const tasks = this.#config.exporters.map(exporter =>
-      exporter.export(exportSpec).catch(err => {
-        if (this.#logger) {
-          this.#logger.warn(err)
-        }
+      exporter.export(exportSpec).catch(error => {
+        log.warn(error)
       })
     )
 

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

@@ -51,8 +51,7 @@ function labelFromStrStr (stringTable, keyStr, valStr) {
 }
 
 function getMaxSamples (options) {
-  const flushInterval = options.flushInterval || 65 * 1e3 // 65 seconds
-  const maxCpuSamples = flushInterval / options.samplingInterval
+  const maxCpuSamples = options.flushInterval / options.samplingInterval
 
   // The lesser of max parallelism and libuv thread pool size, plus one so we can detect
   // oversubscription on libuv thread pool, plus another one for GC.
@@ -403,7 +402,7 @@ class EventsProfiler {
 
   get type () { return 'events' }
 
-  constructor (options = {}) {
+  constructor (options) {
     this.#maxSamples = getMaxSamples(options)
     this.#timelineSamplingEnabled = !!options.timelineSamplingEnabled
     this.#eventSerializer = new EventSerializer(this.#maxSamples)

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,25 +241,32 @@ 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 {
       return require('./profiler').start(config)
-    } catch (e) {
+    } catch (error) {
       log.error(
         'Error starting profiler. For troubleshooting tips, see <https://dtdg.co/nodejs-profiler-troubleshooting>',
-        e
+        error
       )
       return false
     }
   }
 
+  /**
+   * @param {import('./config/config-base')} config - Tracer configuration
+   */
   #updateTracing (config) {
     if (config.tracing !== false) {
       if (config.appsec.enabled) {
@@ -269,7 +279,12 @@ class Tracer extends NoopProxy {
         const prioritySampler = config.apmTracingEnabled === false
           ? require('./standalone').configure(config)
           : undefined
-        this._tracer = new DatadogTracer(config, prioritySampler)
+        let otlpExporter
+        if (config.otelTracesEnabled) {
+          const { buildResourceAttributes, createOtlpTraceExporter } = require('./opentelemetry/trace')
+          otlpExporter = createOtlpTraceExporter(config, buildResourceAttributes(config))
+        }
+        this._tracer = new DatadogTracer(config, prioritySampler, otlpExporter)
         this.dataStreamsCheckpointer = this._tracer.dataStreamsCheckpointer
         lazyProxy(this, 'appsec', () => require('./appsec/sdk'), this._tracer, config)
         lazyProxy(this, 'llmobs', () => require('./llmobs/sdk'), this._tracer, this._modules.llmobs, config)
@@ -330,6 +345,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`)