add-new-configuration

## When to Use This Skill Use this skill whenever a code change introduces a **new environment variable** (or renames/aliases an existing one). In dd-trace-py every `DD_*`, `_DD_*`, `OTEL_*`, or `DATADOG_*` variable accessed under `ddtrace/` MUST be registered, or the `supported_configurations` CI check fails. Typical trigger: you just added something like `DDConfig.var(bool, AI_GUARD.ENV_OPENAI_ENABLED, default=True)` in a settings module and need to make CI / docs happy. --- ## Key Principles 1. **`supported-configurations.json` is the source of truth.** Edit it by hand; everything else is generated or verified from it. 2. **Never hand-edit `ddtrace/internal/settings/_supported_configurations.py`** — it is AUTO-GENERATED. Run the script to regenerate it. 3. **Keep entries alphabetically sorted** within the `supportedConfigurations` object (the generator sorts the Python module, but keep the JSON tidy too). 4. **Document user-facing variables** in `docs/configuration.rst` under the correct product section. 5. **Hand off to the human** to add the variable to the feature-parity registry — this is an external web app the agent cannot edit. --- ## Steps ### 1. Add the entry to `supported-configurations.json` Find the right alphabetical slot and add a single-element array. Set `type` to mirror the `DDConfig.var(...)` type. Do NOT infer the `implementation` letter from neighbouring variables — it is owned by the central Configuration Registry (see step 6). Use `"A"` for a brand-new key; if the key already exists in the registry, reuse its letter, and if a maintainer must create a new implementation version (because the type/default differs from an existing cross-language entry), reference that version's letter. ```json "DD_AI_GUARD_OPENAI_ENABLED": [ { "implementation": "A", "type": "boolean", "default": "true" } ], ``` Field notes: - `type`: one of `boolean`, `string`, `int`, etc. — mirror the `DDConfig.var(...)` type. - `default`: the **string** form of the default (`"true"`, `"16"`, or `null` for no default). Must match the code default exactly. - `implementation`: the version letter assigned by the central Configuration Registry (step 6), NOT inferred from neighbouring vars. A product prefix like `DD_TRACE_`/`DD_APPSEC_` legitimately mixes multiple letters, so copying a sibling can write the wrong value and only the central CI will catch it. - Optional keys seen in the registry: `aliases`, `deprecated`, `sensitive` (excludes the value from config telemetry). Add these only when applicable. ### 2. Regenerate the Python module ```bash python scripts/supported_configurations.py ``` This rewrites `ddtrace/internal/settings/_supported_configurations.py` (`SUPPORTED_CONFIGURATIONS`, `CONFIGURATION_ALIASES`, `DEPRECATED_CONFIGURATIONS`, `SENSITIVE_CONFIGURATIONS`) and verifies that every env var accessed in `ddtrace/` is registered. ### 3. Verify everything is in sync ```bash python scripts/supported_configurations.py --check ``` Expected output: ``` _supported_configurations.py is up to date. Registry is complete (NNN entries, no unregistered vars). ``` This is the same check CI runs. If it reports unregistered vars, you missed an entry in step 1. ### 4. Document the variable in `docs/configuration.rst` Add an entry under the appropriate product heading using the `.. ddtrace-configuration-options::` directive. Match the surrounding style. ```rst DD_AI_GUARD_OPENAI_ENABLED: type: Boolean default: True description: | Per-provider kill switch for AI Guard auto-instrumentation of the OpenAI SDK. When set to ``False``, disables AI Guard instrumentation for OpenAI only. ``` Include `version_added:` if the option is gated to a specific release. ### 5. Add a release note (if user-impacting) New public configuration is user-facing, so add a Reno fragment (use the `releasenote` skill). Skip only for purely internal/private vars. ### 6. Hand off: add it to the feature-parity registry The agent CANNOT do this — it is an external web application. Tell the user: > ⚠️ **Action required:** Add this configuration to the cross-language > feature-parity registry so it is tracked across tracer languages: > https://feature-parity.us1.prod.dog/#/configurations?viewType=configurations --- ## Validation Checklist - [ ] Entry added to `supported-configurations.json` (correct type/default/implementation). - [ ] `python scripts/supported_configurations.py` run (module regenerated). - [ ] `python scripts/supported_configurations.py --check` passes. - [ ] Documented in `docs/configuration.rst` under the right section. - [ ] Release note added (if user-impacting). - [ ] User reminded to register it at the feature-parity dashboard. --- ## Gotchas - The `--check` step is what CI enforces; always run it before committing. - `default` in the JSON is a **string** (or `null`), even for ints/booleans. - If you only consume the variable in tests or tooling outside `ddtrace/`, the completeness check won't force registration — but register it anyway if it is a real, documented configuration option. - Renames: treat the old name as an `alias` rather than deleting it, to avoid breaking existing deployments.