feat(config): centralize env var deprecation handling in the registry

[bm1549]

Description

Adding a new env-var deprecation should be a JSON edit, not a deprecate(...) call placed at the right line. This PR moves deprecation metadata into a nested deprecation: {...} block in supported-configurations.json and has Config.__init__ sweep the registry for set deprecated vars, firing one DDTraceDeprecationWarning per process via warnings.warn.

The four scattered manual call sites (_config.py ×2, asgi/middleware.py, pytest/_plugin_v2.py) are removed; their metadata now lives in the JSON.

Schema

deprecated: true remains the cross-tracer-compatible signal. The new deprecation: {...} block carries Python-tracer metadata. removal_version is required for any deprecated entry; the generator rejects entries without it.

"DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED": [
  {
    "implementation": "A", "type": "boolean", "default": "true",
    "deprecated": true,
    "deprecation": {
      "removal_version": "5.0.0",
      "extra_message": "128-bit trace ID generation will become mandatory in version 5.0.0."
    }
  }
]

Alias-only deprecation uses deprecation.aliases.<NAME>: {removal_version, replaced_by, extra_message} on the canonical entry, without deprecated: true at the top level. Used here for DD_TRACE_INFERRED_SPANS_ENABLED → DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED.

Migrated entries

• DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED (removal 5.0.0)
• DD_TRACE_INFERRED_SPANS_ENABLED → DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED (5.0.0)
• DD_ASGI_TRACE_WEBSOCKET → DD_TRACE_WEBSOCKET_MESSAGES_ENABLED (5.0.0; was previously only a log.warning)
• DD_PYTEST_USE_NEW_PLUGIN_BETA (3.0.0)
• Pre-existing deprecated entries (DATADOG_TAGS, DATADOG_TRACE_AGENT_HOSTNAME, DD_COMPILE_DEBUG) get removal_version: 5.0.0 to satisfy the new schema requirement.

Drive-by

Registers DD_PROFILING_MEMORY_MEM_DOMAIN_ENABLED (added in #17886 without a registry entry, was breaking supported_configurations --check).

Testing

• tests/internal/test_supported_configurations_deprecations.py (new): asserts the DEPRECATED_CONFIGURATIONS dict shape, alias-only-deprecation handling, and that every entry has a removal_version.
• tests/internal/test_env.py (extended): set var fires, alias fires, once-only (atomic via setdefault+sentinel), __contains__ silent (set and unset), unset var silent, warn_deprecated_set_vars sweep, single warning across Config() construction.
• python scripts/supported_configurations.py --check passes; scripts/lint fmt && scripts/lint typing clean.

Risks

• DD_ASGI_TRACE_WEBSOCKET previously emitted only a log.warning; now fires DDTraceDeprecationWarning through the standard Python warnings pipeline. Called out in the release note.
• Config.__init__ now runs a sweep over DEPRECATED_CONFIGURATIONS (~8 entries) at bootstrap. Negligible on a one-shot startup path.

[cit-pr-commenter-54b7da]

Codeowners resolved as

ddtrace/internal/settings/env.py                                        @DataDog/apm-sdk-capabilities-python
tests/internal/test_env.py                                              @DataDog/apm-sdk-capabilities-python

[datadog-prod-us1-5]

 

✨ Fix all issues with BitsAI

⚠️ Warnings

🚦 1 Pipeline job failed

DataDog/apm-reliability/dd-trace-py | download win_arm64 wheels     

🛟 This job is unlikely to succeed on retry. Please review your pipeline configuration.

RUN_ID not found. Check if the GitHub build jobs were successfully triggered on your PR.

ℹ️ Info

No other issues found (see more)

🧪 All tests passed
❄️ No new flaky tests detected

🚧 81 tests that failed were ignored due to quarantine

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 1ff3ba4 | Docs | Datadog PR Page | Give us feedback!}

[bm1549]

This was missed from the 3.x release, but to avoid potentially breaking changes on a minor version, I was leaning to drop this in 5.x with the rest of the configs

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-05-19 20:44:16

Comparing candidate commit 1ff3ba4 in PR branch brian.marks/registry-deprecations with baseline commit a6282d1 in branch main.

Found 0 performance improvements and 9 performance regressions! Performance is the same for 599 metrics, 10 unstable metrics.

scenario:httppropagationinject-ids_only

• 🟥 execution_time [+1.569µs; +1.735µs] or [+7.764%; +8.583%]

scenario:iastaspects-stringio_aspect

• 🟥 execution_time [+631.336µs; +665.538µs] or [+16.482%; +17.375%]

scenario:iastaspectsospath-ospathbasename_aspect

• 🟥 execution_time [+105.100µs; +112.577µs] or [+24.749%; +26.510%]

scenario:iastaspectssplit-rsplit_aspect

• 🟥 execution_time [+12.062µs; +16.548µs] or [+8.142%; +11.170%]

scenario:iastaspectssplit-split_aspect

• 🟥 execution_time [+10.713µs; +14.656µs] or [+7.382%; +10.099%]

scenario:iastaspectssplit-splitlines_aspect

• 🟥 execution_time [+10.934µs; +13.962µs] or [+7.702%; +9.835%]

scenario:span-start

• 🟥 execution_time [+1.495ms; +1.642ms] or [+9.626%; +10.573%]

scenario:telemetryaddmetric-1-count-metric-1-times

• 🟥 execution_time [+220.398ns; +271.490ns] or [+10.552%; +12.998%]

scenario:tracer-small

• 🟥 execution_time [+24.948µs; +26.945µs] or [+7.399%; +7.992%]