refactor(config)!: gate experimental.appsec, plugins, ingestion shapes (#8318)

BridgeAR · web-flow · commit 4ab60e255153 · 2026-05-12T13:36:22.000+02:00
Gates three long-@deprecated programmatic config shapes for v6 in defaults.js; v5 keeps them. The `experimental.appsec.*` programmatic aliases (including the bare boolean alias and `experimental.appsec.standalone.enabled`) and the `ingestion: { sampleRate, rateLimit }` wrapper are no longer accepted on `tracer.init()` in v6. v5 keeps the legacy shape; v6 callers see an "Unknown option" warning instead of a silent rewrite to the canonical fields, and `DD_EXPERIMENTAL_APPSEC_STANDALONE_ENABLED` is dropped so v6 falls through to `apmTracingEnabled` / `DD_APM_TRACING_ENABLED`. The v6 mutation runs through a shared `major-overrides` helper that both `helper.js` and `defaults.js` invoke before reading `supportedConfigurations`, so the helper layer's alias / deprecation caches and the defaults layer's `optionsTable` build see the same v6 shape regardless of which module is required first.
diff --git a/MIGRATING.md b/MIGRATING.md
@@ -68,6 +68,19 @@ the existing `'b3multi'` value. The legacy `'b3 single header'` spelling is
 still accepted on `DD_TRACE_PROPAGATION_STYLE` and the programmatic option as
 a quiet alias for `'b3'`; prefer the canonical `'b3'` going forward.
 
+### `experimental.appsec` configuration removed
+
+The `experimental.appsec.*` programmatic aliases (and
+`experimental.appsec.standalone.enabled`) have been removed. Use the canonical
+top-level `appsec.*` fields, and `apmTracingEnabled` (or
+`DD_APM_TRACING_ENABLED`) to control standalone ASM mode.
+
+### `ingestion` option removed
+
+The `ingestion: { sampleRate, rateLimit }` wrapper has been removed. Set
+`sampleRate` and `rateLimit` directly on the top-level `TracerOptions` object,
+or use `DD_TRACE_SAMPLE_RATE` / `DD_TRACE_RATE_LIMIT`.
+
 ## 4.0 to 5.0
 
 ### Node 16 is no longer supported
diff --git a/docs/test.ts b/docs/test.ts
@@ -46,10 +46,6 @@ tracer.init({
   version: '1.0.0',
   url: 'http://localhost',
   runtimeMetrics: true,
-  ingestion: {
-    sampleRate: 0.5,
-    rateLimit: 500
-  },
   experimental: {
     exporter: 'log'
   },
@@ -149,13 +145,6 @@ tracer.init({
 });
 
 tracer.init({
-  experimental: {
-    appsec: {
-      standalone: {
-        enabled: true
-      }
-    }
-  },
   iast: {
     enabled: true,
     requestSampling: 50,
diff --git a/eslint-rules/eslint-config-names-sync.mjs b/eslint-rules/eslint-config-names-sync.mjs
@@ -6,14 +6,24 @@ import ts from 'typescript'
 
 const require = createRequire(import.meta.url)
 const { DD_MAJOR } = require('../version.js')
-const { applyMajorVersionAliasFilters } = require('../packages/dd-trace/src/config/major-version-filters.js')
+const applyMajorOverrides = require('../packages/dd-trace/src/config/major-overrides.js')
 
 const IGNORED_CONFIGURATION_NAMES = new Set([
   // v6 drops `experimental.b3` from `index.d.ts`; v5 still consumes the env var.
   'experimental.b3',
   'tracePropagationStyle',
   'tracing',
 ])
+// Configuration name prefixes that are intentionally only present in
+// `supported-configurations.json` for v5 backports and stripped at runtime in
+// v6. Keep these out of the `index.d.ts` ↔ JSON parity check.
+const IGNORED_CONFIGURATION_NAME_PREFIXES = [
+  'experimental.appsec.',
+  'ingestion.',
+]
+const IGNORED_CONFIGURATION_LEAVES = new Set([
+  'experimental.appsec',
+])
 const UNSUPPORTED_CONFIGURATION_ROOTS = new Set([
   'isCiVisibility',
   'logger',
@@ -83,7 +93,7 @@ function createInspectionResult (overrides) {
 function getSupportedConfigurationInfo (filePath) {
   const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'))
   const supportedConfigurations = parsed?.supportedConfigurations
-  applyMajorVersionAliasFilters(supportedConfigurations, DD_MAJOR)
+  applyMajorOverrides(supportedConfigurations, DD_MAJOR)
 
   const names = new Set()
   const primaryEnvTargets = new Map()
@@ -121,14 +131,19 @@ function getSupportedConfigurationInfo (filePath) {
       }
 
       for (const name of entry.configurationNames ?? []) {
-        if (typeof name === 'string' && !IGNORED_CONFIGURATION_NAMES.has(name)) {
-          // Deprecated entries opt out of the cross-check against `index.d.ts` so a
-          // major-version drop of the public type does not strand the env var here.
-          if (!entry.deprecated) {
-            names.add(name)
-          }
-          targets.add(name)
+        if (typeof name !== 'string' || IGNORED_CONFIGURATION_NAMES.has(name)) {
+          continue
+        }
+        if (IGNORED_CONFIGURATION_LEAVES.has(name)) {
+          continue
+        }
+        if (IGNORED_CONFIGURATION_NAME_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+          continue
+        }
+        if (!entry.deprecated) {
+          names.add(name)
         }
+        targets.add(name)
       }
     }
 
@@ -485,6 +500,14 @@ function getIndexDtsConfigurationNames (filePath, supportedConfigurationInfo) {
   for (const ignoredConfigurationName of IGNORED_CONFIGURATION_NAMES) {
     names.delete(ignoredConfigurationName)
   }
+  for (const leaf of IGNORED_CONFIGURATION_LEAVES) {
+    names.delete(leaf)
+  }
+  for (const name of names) {
+    if (IGNORED_CONFIGURATION_NAME_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+      names.delete(name)
+    }
+  }
 
   return names
 }
diff --git a/index.d.ts b/index.d.ts
@@ -699,28 +699,6 @@ declare namespace tracer {
      */
     protocolVersion?: string
 
-    /**
-     * Deprecated in favor of the global versions of the variables provided under this option
-     *
-     * @deprecated
-     * @hidden
-     */
-    ingestion?: {
-      /**
-       * Controls the ingestion sample rate (between 0 and 1) between the agent and the backend.
-       * @env DD_TRACE_SAMPLE_RATE
-       * Programmatic configuration takes precedence over the environment variables listed above.
-       */
-      sampleRate?: number
-
-      /**
-       * Controls the ingestion rate limit between the agent and the backend. Defaults to deferring the decision to the agent.
-       * @env DD_TRACE_RATE_LIMIT
-       * Programmatic configuration takes precedence over the environment variables listed above.
-       */
-      rateLimit?: number
-    };
-
     /**
      * Whether to enable inferred proxy services.
      * @default false
@@ -758,28 +736,6 @@ declare namespace tracer {
        */
       enableGetRumData?: boolean
 
-      /**
-       * Configuration of the AppSec. Can be a boolean as an alias to `appsec.enabled`.
-       * @deprecated Please use the non-experimental `appsec` option instead.
-       */
-      appsec?: boolean | {
-        /**
-         * Configuration of Standalone ASM mode
-         * Deprecated in favor of `apmTracingEnabled`.
-         *
-         * @deprecated Please use `apmTracingEnabled` instead.
-         */
-        standalone?: {
-          /**
-           * Whether to enable Standalone ASM.
-           * @default false
-           * @env DD_EXPERIMENTAL_APPSEC_STANDALONE_ENABLED
-           * Programmatic configuration takes precedence over the environment variables listed above.
-           */
-          enabled?: boolean
-        }
-      } | TracerOptions['appsec'],
-
       aiguard?: {
         /**
          * Set to `true` to enable the SDK.
diff --git a/packages/dd-trace/src/config/defaults.js b/packages/dd-trace/src/config/defaults.js
@@ -4,20 +4,19 @@ const dns = require('dns')
 const util = require('util')
 
 const { DD_MAJOR } = require('../../../../version')
-const { applyMajorVersionAliasFilters } = require('./major-version-filters')
 const { parsers, transformers, telemetryTransformers, setWarnInvalidValue } = require('./parsers')
+const applyMajorOverrides = require('./major-overrides')
 const {
   supportedConfigurations,
 } = /** @type {import('./helper').SupportedConfigurationsJson} */ (require('./supported-configurations.json'))
 
+applyMajorOverrides(supportedConfigurations, DD_MAJOR)
+
 let log
 let seqId = 0
 const configWithOrigin = new Map()
 const parseErrors = new Map()
 
-// Idempotent; mirrors the call in `helper.js` so either module load order produces the same shape.
-applyMajorVersionAliasFilters(supportedConfigurations, DD_MAJOR)
-
 if (DD_MAJOR < 6) {
   // Default value for DD_TRACE_STARTUP_LOGS is 'false' in older major versions.
   // TODO: Remove this here once v5 is not supported anymore.
diff --git a/packages/dd-trace/src/config/helper.js b/packages/dd-trace/src/config/helper.js
@@ -21,16 +21,13 @@
  */
 
 const { deprecate } = require('util')
-
 const { DD_MAJOR } = require('../../../../version')
-const { applyMajorVersionAliasFilters } = require('./major-version-filters')
+const applyMajorOverrides = require('./major-overrides')
 const {
   supportedConfigurations,
 } = /** @type {SupportedConfigurationsJson} */ (require('./supported-configurations.json'))
 
-// Apply v6 env-alias deletions before the `aliases` / `aliasToCanonical` snapshot below; otherwise
-// `getEnvironmentVariables()` keeps rewriting the deprecated env vars to their canonical names.
-applyMajorVersionAliasFilters(supportedConfigurations, DD_MAJOR)
+applyMajorOverrides(supportedConfigurations, DD_MAJOR)
 
 /**
  * Types for environment variable handling.
diff --git a/packages/dd-trace/src/config/major-overrides.js b/packages/dd-trace/src/config/major-overrides.js
@@ -4,37 +4,33 @@
  * @typedef {import('./helper').SupportedConfigurationsJson['supportedConfigurations']} SupportedConfigurations
  */
 
+const EXPERIMENTAL_APPSEC_PREFIX = 'experimental.appsec'
 const EXPERIMENTAL_IAST_PREFIX = 'experimental.iast'
-
-const filtered = new WeakSet()
+const INGESTION_PREFIX = 'ingestion.'
 
 /**
- * Shared between `helper.js` / `defaults.js` (runtime) and `eslint-config-names-sync` (lint) so
- * the JSON ↔ `index.d.ts` sync check uses the same view as the runtime parser. Idempotent on a
- * per-object basis so callers don't have to coordinate load order.
- *
  * @param {SupportedConfigurations} supportedConfigurations Mutated in place.
  * @param {number} majorVersion
  */
-function applyMajorVersionAliasFilters (supportedConfigurations, majorVersion) {
-  if (filtered.has(supportedConfigurations)) return
-  filtered.add(supportedConfigurations)
-
+function applyMajorOverrides (supportedConfigurations, majorVersion) {
   if (majorVersion < 6) return
 
-  // v6 strips both the bare `experimental.iast` alias and its nested forms so
-  // `#applyOptions` warns "Unknown option" instead of writing user-supplied
-  // objects into `iast.enabled` via the bare alias.
   for (const entries of Object.values(supportedConfigurations)) {
     for (const entry of entries) {
       if (Array.isArray(entry.configurationNames)) {
         entry.configurationNames = entry.configurationNames.filter(
-          (name) => name !== EXPERIMENTAL_IAST_PREFIX && !name.startsWith(`${EXPERIMENTAL_IAST_PREFIX}.`)
+          (name) =>
+            name !== EXPERIMENTAL_APPSEC_PREFIX &&
+            name !== EXPERIMENTAL_IAST_PREFIX &&
+            !name.startsWith(`${EXPERIMENTAL_APPSEC_PREFIX}.`) &&
+            !name.startsWith(`${EXPERIMENTAL_IAST_PREFIX}.`) &&
+            !name.startsWith(INGESTION_PREFIX)
         )
+        if (entry.configurationNames.length === 0) delete entry.configurationNames
       }
     }
   }
-
+  delete supportedConfigurations.DD_EXPERIMENTAL_APPSEC_STANDALONE_ENABLED
   delete supportedConfigurations.DD_TRACE_EXPERIMENTAL_B3_ENABLED
 
   /* eslint-disable eslint-rules/eslint-env-aliases */
@@ -62,10 +58,6 @@ function applyMajorVersionAliasFilters (supportedConfigurations, majorVersion) {
 }
 
 /**
- * Filter aliases on a canonical entry in-place. `dropPredicate` may be a string (exact match) or
- * a function called per alias. No-op when the canonical is missing so this stays usable against
- * the eslint sync test fixtures.
- *
  * @param {SupportedConfigurations[string] | undefined} entries
  * @param {string | ((alias: string) => boolean)} dropPredicate
  */
@@ -76,7 +68,9 @@ function dropAlias (entries, dropPredicate) {
     ? (alias) => alias === dropPredicate
     : dropPredicate
   entry.aliases = entry.aliases.filter((alias) => !matches(alias))
-  if (entry.aliases.length === 0) delete entry.aliases
+  if (entry.aliases.length === 0) {
+    delete entry.aliases
+  }
 }
 
-module.exports = { applyMajorVersionAliasFilters }
+module.exports = applyMajorOverrides
diff --git a/packages/dd-trace/test/config/index.spec.js b/packages/dd-trace/test/config/index.spec.js
