用途:当代码变更引入新的环境变量(或重命名、设置别名)时使用。在 dd-trace-py 中,ddtrace/ 下访问的每个 DD_、DD、OTEL_、DATADOG_ 变量都必须注册,否则 supported_configurations CI 检查会失败。典型触发场景是刚在 settings 模块中加入类似 DDConfig.var(bool, AI_GUARD.ENV_OPENAI_ENABLED, default=True) 的配置。
主要能力与原则:supported-configurations.json 是唯一事实来源,需手工编辑,其余内容由它生成或校验;不要手工修改自动生成的 ddtrace/internal/settings/_supported_configurations.py;条目在 supportedConfigurations 对象内按字母排序;面向用户的变量需写入 docs/configuration.rst 对应产品章节;跨语言 feature-parity 注册表需交由人工在外部 Web 应用完成。
使用方式:第一步在 supported-configurations.json 中按字母位置添加单元素数组,type 与 DDConfig.var(...) 类型一致,default 为默认值的字符串形式(无默认用 null),implementation 字母由中央 Configuration Registry 分配,新键用 "A",不要照抄相邻变量;可选键 aliases、deprecated、sensitive 仅在适用时添加。第二步运行 python scripts/supported_configurations.py 重新生成模块。第三步运行 python scripts/supported_configurations.py --check 校验,预期输出为模块已最新、注册表完整。第四步在 docs/configuration.rst 用 .. ddtrace-configuration-options:: 指令补充文档,必要时加 version_added。第五步若影响用户则添加 Reno 发布说明。第六步提醒用户到 feature-parity 仪表盘登记。
限制与注意:--check 是 CI 强制项,提交前必须通过;JSON 中 default 始终是字符串或 null;仅在测试或 ddtrace/ 之外工具中使用的变量不会被完整性检查强制注册,但真实且已文档化的配置仍应注册;重命名时把旧名保留为别名而非删除,以免破坏现有部署。feature-parity 注册表为外部应用,本技能无法代为编辑。