dd-trace 5.109.0 → 5.111.0

package/packages/dd-trace/src/config/helper.js

@@ -10,6 +10,7 @@
  * @property {string[]} [aliases]
  * @property {string[]} [configurationNames]
  * @property {string} [internalPropertyName]
+ * @property {string} [namespace] Nests the canonical env name under this property path (e.g. `telemetry`).
  * @property {string} [transform]
  * @property {string} [allowed]
  * @property {string|boolean} [deprecated]
@@ -149,7 +150,140 @@ function validateAccess (name) {
   }
 }
 
+let configurationsTable
+let configDefaults
+
+// Lazy require to keep the `config -> helper` import direction acyclic: helper
+// must not pull `config/defaults` at module load. `config/defaults` defers its
+// own instrumented `dns` require until after it exports, so by the time any
+// caller resolves a value the table is fully populated.
+function loadConfigurationsTable () {
+  if (configurationsTable === undefined) {
+    const defaultsModule = require('./defaults')
+    configurationsTable = defaultsModule.configurationsTable
+    configDefaults = defaultsModule.defaults
+  }
+}
+
+/**
+ * Parses and transforms a raw environment value with the same parser and
+ * transformer Config applies when it reads environment sources, so callers
+ * receive the typed value instead of the raw string.
+ *
+ * @param {string} name Canonical or alias environment variable name.
+ * @param {string} value Raw value read from an environment source.
+ * @param {'env_var'|'fleet_stable_config'|'local_stable_config'} source Source the value was read from.
+ * @returns {string | number | boolean | object | undefined}
+ */
+function parseConfigurationValue (name, value, source) {
+  loadConfigurationsTable()
+  const canonical = aliasToCanonical[name] ?? name
+  const entry = configurationsTable[canonical]
+  const parsed = entry.parser(value, canonical, source)
+  return parsed !== undefined && entry.transformer ? entry.transformer(parsed, canonical, source) : parsed
+}
+
+/**
+ * Returns the registered default for a configuration — the same value Config
+ * resolves when no environment source sets it.
+ *
+ * @param {string} name Canonical or alias environment variable name.
+ * @returns {string | number | boolean | object | undefined}
+ */
+function getRegisteredDefault (name) {
+  loadConfigurationsTable()
+  const canonical = aliasToCanonical[name] ?? name
+  const entry = configurationsTable[canonical]
+  return configDefaults[entry.property ?? canonical]
+}
+
+/** @typedef {import('./generated-config-types').GeneratedEnvVarConfig} GeneratedEnvVarConfig */
+
+/**
+ * Returns the value stored at the given name, assumed to be in environment variable format,
+ * from the supported env sources (process.env, local stable config, fleet stable config).
+ * Falls back to aliases if the canonical name is not set.
+ *
+ * The raw value is parsed and transformed exactly as Config does when it reads environment
+ * sources, so the returned value is typed (boolean, number, array, map, ...) rather than the
+ * raw string. A literal supported name resolves to its specific configured type.
+ *
+ * When the name is not set in any source, the registered default is returned, so callers can
+ * use the value directly. Callers that must distinguish an explicitly configured value from the
+ * default (e.g. an OTel fallback that only applies when the option is unset) pass `skipDefault`
+ * to receive `undefined` for an unset value instead. All sources (process.env, local and fleet
+ * stable config) are read in both modes.
+ *
+ * @template {keyof GeneratedEnvVarConfig} TName
+ * @overload
+ * @param {TName} name Environment variable name
+ * @returns {GeneratedEnvVarConfig[TName]}
+ */
+/**
+ * @template {keyof GeneratedEnvVarConfig} TName
+ * @overload
+ * @param {TName} name Environment variable name
+ * @param {boolean} skipDefault Return `undefined` instead of the registered default when unset.
+ * @returns {GeneratedEnvVarConfig[TName] | undefined}
+ */
+/**
+ * @overload
+ * @param {string} name Environment variable name
+ * @param {boolean} [skipDefault] Return `undefined` instead of the registered default when unset.
+ * @returns {string | number | boolean | object | undefined}
+ */
+/**
+ * @param {string} name
+ * @param {boolean} [skipDefault]
+ * @throws {Error} if the configuration is not supported
+ */
+function getValueFromEnvSources (name, skipDefault) {
+  validateAccess(name)
+
+  if (!stableConfigLoaded) {
+    loadStableConfig()
+  }
+
+  // Sources are read in priority order (fleet > env > local). A value the parser
+  // or transformer rejects resolves to `undefined` and is ignored, falling
+  // through to the next source and finally the registered default — mirroring
+  // how Config applies env sources (`setAndTrack` skips such values). This keeps
+  // a malformed higher-priority value (e.g. a fleet-stable `DD_TRACE_DEBUG=maybe`)
+  // from masking a valid `DD_TRACE_DEBUG=true`.
+  if (fleetStableConfig !== undefined) {
+    const fromFleet = getValueFromSource(name, fleetStableConfig)
+    if (fromFleet !== undefined) {
+      const parsed = parseConfigurationValue(name, fromFleet, 'fleet_stable_config')
+      if (parsed !== undefined) {
+        return parsed
+      }
+    }
+  }
+
+  const fromEnv = getValueFromSource(name, process.env)
+  if (fromEnv !== undefined) {
+    const parsed = parseConfigurationValue(name, fromEnv, 'env_var')
+    if (parsed !== undefined) {
+      return parsed
+    }
+  }
+
+  if (localStableConfig !== undefined) {
+    const fromLocal = getValueFromSource(name, localStableConfig)
+    if (fromLocal !== undefined) {
+      const parsed = parseConfigurationValue(name, fromLocal, 'local_stable_config')
+      if (parsed !== undefined) {
+        return parsed
+      }
+    }
+  }
+
+  return skipDefault ? undefined : getRegisteredDefault(name)
+}
+
 module.exports = {
+  getValueFromEnvSources,
+
   /**
    * Expose raw stable config maps and warnings for consumers that need
    * per-source access (e.g. telemetry in Config).
@@ -209,39 +343,6 @@ module.exports = {
     return getValueFromSource(name, process.env)
   },
 
-  /**
-   * Returns the value stored at the given name, assumed to be in environment variable format,
-   * from the supported env sources (process.env, local stable config, fleet stable config).
-   * Falls back to aliases if the canonical name is not set.
-   *
-   * @param {string} name Environment variable name
-   * @returns {string|undefined}
-   * @throws {Error} if the configuration is not supported
-   */
-  getValueFromEnvSources (name) {
-    validateAccess(name)
-
-    if (!stableConfigLoaded) {
-      loadStableConfig()
-    }
-
-    if (fleetStableConfig !== undefined) {
-      const fromFleet = getValueFromSource(name, fleetStableConfig)
-      if (fromFleet !== undefined) {
-        return fromFleet
-      }
-    }
-
-    const fromEnv = getValueFromSource(name, process.env)
-    if (fromEnv !== undefined) {
-      return fromEnv
-    }
-
-    if (localStableConfig !== undefined) {
-      return getValueFromSource(name, localStableConfig)
-    }
-  },
-
   /**
    * Returns the actual environment variable name used for a supported configuration
    * from a specific environment-based source.

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

@@ -7,7 +7,7 @@ const { URL, format } = require('node:url')
 const rfdc = require('../../../../vendor/dist/rfdc')({ proto: false, circles: false })
 const uuid = require('../../../../vendor/dist/crypto-randomuuid') // we need to keep the old uuid dep because of cypress
 const set = require('../../../datadog-core/src/utils/src/set')
-const { DD_MAJOR } = require('../../../../version')
+const { DD_MAJOR, NODE_MAJOR } = require('../../../../version')
 const log = require('../log')
 const pkg = require('../pkg')
 const { isTrue } = require('../util')
@@ -25,6 +25,7 @@ const {
   getEnvironmentVariable,
   getEnvironmentVariables,
   getStableConfigSources,
+  getValueFromEnvSources,
 } = require('./helper')
 const {
   defaults,
@@ -245,12 +246,12 @@ class Config extends ConfigBase {
       let entry = optionsTable[fullName]
       if (!entry) {
         // TODO: Fix this by by changing remote config to use env styles.
-        if (name !== 'tracing' || source !== 'remote_config') {
+        if (name !== 'DD_TRACE_ENABLED' || source !== 'remote_config') {
           log.warn('Unknown option %s with value %o', fullName, value)
           continue
         }
         // @ts-expect-error - The entry is defined in the configurationsTable.
-        entry = configurationsTable.tracing
+        entry = configurationsTable.DD_TRACE_ENABLED
       }
 
       if (entry.nestedProperties) {
@@ -286,7 +287,7 @@ class Config extends ConfigBase {
       }
       // TODO: Coerce mismatched types to the expected type, if possible. E.g., strings <> numbers
       const transformed = value !== undefined && entry.transformer ? entry.transformer(value, fullName, source) : value
-      setAndTrack(this, entry.property, transformed, value, source)
+      setAndTrack(this, entry.property ?? name, transformed, value, source)
     }
   }
 
@@ -358,18 +359,22 @@ class Config extends ConfigBase {
       setAndTrack(this, 'OTEL_TRACES_EXPORTER', 'none')
     }
 
-    if (this.telemetry.heartbeatInterval) {
-      setAndTrack(this, 'telemetry.heartbeatInterval', Math.floor(this.telemetry.heartbeatInterval * 1000))
+    if (this.telemetry.DD_TELEMETRY_HEARTBEAT_INTERVAL) {
+      setAndTrack(this, 'telemetry.DD_TELEMETRY_HEARTBEAT_INTERVAL',
+        Math.floor(this.telemetry.DD_TELEMETRY_HEARTBEAT_INTERVAL * 1000))
     }
-    if (this.telemetry.extendedHeartbeatInterval) {
-      setAndTrack(this, 'telemetry.extendedHeartbeatInterval',
-        Math.floor(this.telemetry.extendedHeartbeatInterval * 1000))
+
+    // Allocation profiling needs a sampling hook only available on Node.js 26+.
+    setAndTrack(this, 'DD_PROFILING_ALLOCATION_ENABLED', NODE_MAJOR >= 26 && this.DD_PROFILING_ALLOCATION_ENABLED)
+    if (this.telemetry.DD_TELEMETRY_EXTENDED_HEARTBEAT_INTERVAL) {
+      setAndTrack(this, 'telemetry.DD_TELEMETRY_EXTENDED_HEARTBEAT_INTERVAL',
+        Math.floor(this.telemetry.DD_TELEMETRY_EXTENDED_HEARTBEAT_INTERVAL * 1000))
     }
 
-    // Enable resourceRenamingEnabled when appsec is enabled and only
+    // Enable resource renaming when appsec is enabled and only
     // if DD_TRACE_RESOURCE_RENAMING_ENABLED is not explicitly set
-    if (!trackedConfigOrigins.has('resourceRenamingEnabled')) {
-      setAndTrack(this, 'resourceRenamingEnabled', this.appsec.enabled ?? false)
+    if (!trackedConfigOrigins.has('DD_TRACE_RESOURCE_RENAMING_ENABLED')) {
+      setAndTrack(this, 'DD_TRACE_RESOURCE_RENAMING_ENABLED', this.appsec.enabled ?? false)
     }
 
     if (!trackedConfigOrigins.has('spanComputePeerService') && this.spanAttributeSchema !== 'v0') {
@@ -377,9 +382,9 @@ class Config extends ConfigBase {
     }
 
     if (!this.apmTracingEnabled) {
-      setAndTrack(this, 'stats.enabled', false)
-    } else if (!trackedConfigOrigins.has('stats.enabled')) {
-      setAndTrack(this, 'stats.enabled', getIsGCPFunction() || getIsAzureFunction())
+      setAndTrack(this, 'stats.DD_TRACE_STATS_COMPUTATION_ENABLED', false)
+    } else if (!trackedConfigOrigins.has('stats.DD_TRACE_STATS_COMPUTATION_ENABLED')) {
+      setAndTrack(this, 'stats.DD_TRACE_STATS_COMPUTATION_ENABLED', getIsGCPFunction() || getIsAzureFunction())
     }
 
     // TODO: Remove the experimental env vars as a major or deprecate the option?
@@ -451,11 +456,11 @@ class Config extends ConfigBase {
     }
 
     // For LLMObs, we want to auto enable it when other llmobs options are defined.
-    if (!this.llmobs.enabled &&
-        !trackedConfigOrigins.has('llmobs.enabled') &&
+    if (!this.llmobs.DD_LLMOBS_ENABLED &&
+        !trackedConfigOrigins.has('llmobs.DD_LLMOBS_ENABLED') &&
         (trackedConfigOrigins.has('llmobs.agentlessEnabled') ||
         trackedConfigOrigins.has('llmobs.mlApp'))) {
-      setAndTrack(this, 'llmobs.enabled', true)
+      setAndTrack(this, 'llmobs.DD_LLMOBS_ENABLED', true)
     }
 
     if (this.OTEL_RESOURCE_ATTRIBUTES) {
@@ -548,14 +553,15 @@ class Config extends ConfigBase {
     this.tags['runtime-id'] = RUNTIME_ID
 
     if (IS_SERVERLESS) {
-      setAndTrack(this, 'telemetry.enabled', false)
+      setAndTrack(this, 'telemetry.DD_INSTRUMENTATION_TELEMETRY_ENABLED', false)
       setAndTrack(this, 'DD_CRASHTRACKING_ENABLED', false)
-      setAndTrack(this, 'remoteConfig.enabled', false)
+      setAndTrack(this, 'remoteConfig.DD_REMOTE_CONFIGURATION_ENABLED', false)
     }
 
     // TODO: Should this unconditionally be disabled?
-    if (getEnvironmentVariable('JEST_WORKER_ID') && !trackedConfigOrigins.has('telemetry.enabled')) {
-      setAndTrack(this, 'telemetry.enabled', false)
+    if (getEnvironmentVariable('JEST_WORKER_ID') &&
+        !trackedConfigOrigins.has('telemetry.DD_INSTRUMENTATION_TELEMETRY_ENABLED')) {
+      setAndTrack(this, 'telemetry.DD_INSTRUMENTATION_TELEMETRY_ENABLED', false)
     }
 
     // Experimental agentless APM span intake
@@ -565,7 +571,7 @@ class Config extends ConfigBase {
     if (agentlessEnabled) {
       setAndTrack(this, 'experimental.exporter', 'agentless')
       // Disable client-side stats computation
-      setAndTrack(this, 'stats.enabled', false)
+      setAndTrack(this, 'stats.DD_TRACE_STATS_COMPUTATION_ENABLED', false)
       // Enable hostname reporting
       setAndTrack(this, 'reportHostname', true)
       // Disable rate limiting - server-side sampling will be used
@@ -599,6 +605,16 @@ class Config extends ConfigBase {
       setAndTrack(this, 'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT', `${defaultOtlpBase}/v1/traces`)
     }
 
+    const autoTraceMetrics = this.OTEL_TRACES_EXPORTER === 'otlp' && this.DD_METRICS_OTEL_ENABLED === true
+    setAndTrack(this, 'OTEL_TRACES_SPAN_METRICS_ENABLED', this.OTEL_TRACES_SPAN_METRICS_ENABLED ?? autoTraceMetrics)
+
+    if (this.OTEL_TRACES_SPAN_METRICS_ENABLED) {
+      this.stats = { ...this.stats, DD_TRACE_STATS_COMPUTATION_ENABLED: true }
+    }
+
+    const flushInterval = getValueFromEnvSources('_DD_TRACE_METRICS_OTEL_FLUSH_INTERVAL')
+    setAndTrack(this, '_DD_TRACE_METRICS_OTEL_FLUSH_INTERVAL', flushInterval)
+
     if (process.platform === 'win32') {
       // OOM monitoring does not work properly on Windows, so it will be disabled.
       deactivateIfEnabledAndWarnOnWindows(this, 'DD_PROFILING_EXPERIMENTAL_OOM_MONITORING_ENABLED')

package/packages/dd-trace/src/config/major-overrides.js

@@ -72,11 +72,13 @@ function applyV5Overrides (supportedConfigurations) {
   const iastEntry = supportedConfigurations.DD_IAST_SECURITY_CONTROLS_CONFIGURATION?.[0]
   if (!iastEntry) return
 
+  // v5 kept this configurable through the (experimental) iast.* programmatic API. The entry
+  // still carries `namespace: "iast"`, so these names route to iast.DD_IAST_SECURITY_CONTROLS_CONFIGURATION
+  // and the property path stays canonical across majors.
   iastEntry.configurationNames = [
-    iastEntry.internalPropertyName || iastEntry.configurationNames?.[0],
+    'iast.securityControlsConfiguration',
     `${EXPERIMENTAL_IAST_PREFIX}.securityControlsConfiguration`,
   ]
-  delete iastEntry.internalPropertyName
 }
 
 /**

package/packages/dd-trace/src/config/parsers.js

@@ -2,7 +2,7 @@
 
 const fs = require('fs')
 
-const { DD_MAJOR } = require('../../../../version')
+const { DD_MAJOR, NODE_MAJOR } = require('../../../../version')
 const tagger = require('../tagger')
 
 let warnInvalidValue
@@ -100,6 +100,24 @@ const transformers = {
     }
     return configValue
   },
+  /**
+   * Parses DD_PROFILING_DEBUG_UPLOAD_COMPRESSION ('on' | 'off' | 'gzip[-1..9]' | 'zstd[-1..22]')
+   * into the codec and level the profiler uploads with. The value's shape is already range-checked
+   * by the `allowed` pattern, so no validation is needed here.
+   *
+   * @param {string} value
+   * @returns {{ method: string, level: number | undefined }}
+   */
+  normalizeProfilingUploadCompression (value) {
+    let [method, level] = value.toLowerCase().split('-')
+    // Default "on" to zstd on Node.js 24+ and gzip earlier. zstd ships everywhere via a Rust
+    // compressor, but 24+ has a built-in that runs on libuv worker threads just as gzip does, so it
+    // is the least disruptive default.
+    if (method === 'on') {
+      method = NODE_MAJOR >= 24 ? 'zstd' : 'gzip'
+    }
+    return { method, level: level ? Number.parseInt(level, 10) : undefined }
+  },
   sampleRate (value, optionName, source) {
     const number = Number(value)
     if (Number.isNaN(number) || value === null) {

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

@@ -228,7 +228,7 @@ const optionLookupTable = {
   code_origin_enabled: 'codeOriginForSpans.enabled',
   tracing_sampling_rate: 'sampleRate',
   log_injection_enabled: 'logInjection',
-  tracing_enabled: 'tracing',
+  tracing_enabled: 'DD_TRACE_ENABLED',
   tracing_sampling_rules: 'samplingRules',
   tracing_header_tags: 'headerTags',
   tracing_tags: 'tags',