OpenTelemetry Spring Boot 声明式配置：同样的占位符，不同的解析边界

明确结论

从 OpenTelemetry Spring Boot starter 2.26.0 起，团队可以在 application.yaml 的 otel 节点下描述处理器、导出器、采样器等完整管线，减少为复杂配置编写定制 Bean 或 Agent 扩展的需要。

迁移的主要风险在配置解析边界：Spring starter 先由 Spring 解析属性，而独立 Java Agent 使用 SDK 自己的替换器。两者都写 ${...}，默认值语法、数据来源和覆盖行为却不同，不能直接复制配置。

核心技术要点

• otel.file_format: '1.0' 是启用声明式配置的开关；其下的树按 OpenTelemetry SDK schema 解析。
• Spring starter 使用 ${VAR:default}，可读取环境变量、JVM 参数、命令行、profile 和外部配置；独立 Agent 使用 ${VAR:-default}，解析范围更窄且不做递归替换。
• Spring 的 relaxed binding 会统一 OTEL_SERVICE_NAME、otel.service.name 等写法，并允许同路径环境变量覆盖 YAML 叶子节点。
• 复杂列表路径需要 starter 额外重建环境变量名称；最终配置被还原成树并绑定到 SDK 配置模型后再启动遥测组件。

适用场景

• 需要多个 exporter、复杂 sampler 或处理器组合的 Spring Boot 服务。
• 希望通过 profile、环境变量和外部配置中心管理不同环境遥测管线的团队。
• 准备从大量 OTEL_* 平铺变量或自定义 Bean 迁移到可审查 YAML 的项目。

实践建议

• 先在单个非关键服务试点，保存启动时的最终配置摘要，并验证 trace、metric、log 三类信号的实际出口。
• 迁移前明确运行形态是 Spring starter 还是独立 Agent，为两套占位符语法分别建立配置测试，禁止跨形态直接复制。
• Spring Boot 3.5+ 项目按官方说明导入 OpenTelemetry instrumentation BOM；时长值使用毫秒数字，例如 5000，而不是 5s。

局限与风险

• Spring Boot starter 的声明式配置支持仍标记为 experimental，schema 与扩展点可能继续变化。
• 程序化定制接口会改变：原 AutoConfigurationCustomizerProvider 需要迁移到声明式配置对应的定制与组件提供机制。
• 配置统一不等于运行正确；错误的采样规则、导出端点或凭据仍可能让遥测静默缺失或产生高额成本。

延伸阅读

原始资料来自 OpenTelemetry Blog。建议结合官方文档的最新版本核对具体 API、限制和配置。