OpenTelemetry Java Agent 3.0 预览版怎样试用

OpenTelemetry Java Agent 3.0 的预览入口是 2.32.0：官方把它定位为 3.0 的 release candidate，但正式版本前仍可能调整行为。正确的试用方式不是直接替换生产 agent，而是在测试部署中先保存旧遥测，再用双发配置比较新旧字段，最后打开总开关检查下游依赖。

官方地址：https://opentelemetry.io/blog/2026/java-agent-3.0-preview/

先把 2.32.0 当作迁移预览工具。重点观察名称、值、类型、单位、消息 trace 父子关系，以及默认开启或关闭的 instrumentation；确认仪表盘和告警能读到新数据后，再扩大范围。

先确认版本和测试边界

OpenTelemetry 官方 Java 入门页当前列出的 Java instrumentation 版本是 2.32.0，GitHub release 也将该版本列为最新 agent release。准备一个可快速回滚的测试 Deployment，保留当前 agent、启动参数、导出端点和基线查询。预览阶段不应把“能启动”当作迁移完成，因为字段名不变时，值和单位也可能改变。

# 只在测试部署中固定预览版本，生产环境保留原来的 agent 包
export OTEL_JAVAAGENT_VERSION=2.32.0
export OTEL_SERVICE_NAME=orders-preview

# 让回滚只需要恢复 agent 包和这一组环境变量
export JAVA_TOOL_OPTIONS="-javaagent:/opt/otel/opentelemetry-javaagent-${OTEL_JAVAAGENT_VERSION}.jar"

如果应用通过容器镜像注入 agent，请把镜像标签、Java 启动参数和 OTLP exporter 配置一起记录。预览配置属于实验开关，不能把它当成 3.0 最终默认值。

先用 dup 同时比较旧、新遥测

官方建议先关闭总开关，再对需要迁移的领域使用 /dup。下面的配置示例覆盖 database、code 和 messaging：它适合建立比较样本，便于看出属性、指标和 trace 结构的差异。

# 先保留旧行为，同时让选定语义约定双发新旧数据
export OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=false
export OTEL_SEMCONV_STABILITY_OPT_IN=database/dup,code/dup
export OTEL_SEMCONV_STABILITY_PREVIEW=messaging/dup

# 启动参数只用于测试服务；不要覆盖已有 OTLP endpoint 配置
java $JAVA_TOOL_OPTIONS -jar orders-service.jar

比较时至少记录四类差异：数据库属性可能从 db.name 转为 db.namespace 等新命名；代码属性可能合并；指标要同时看名称与单位；Kafka 等消息场景要看 span 名称、span kind、父关系和 link。即使查询字段名称不变，也不能假设数值和单位不变。

再打开 v3 preview 总开关

完成双发比较后，再在独立测试实例打开总开关。它会组合启用较新的 database、code 和 messaging 约定，并关闭这些领域的 /dup。此时更接近 3.0 默认行为，适合验证应用启动、导出链路以及查询规则。

# 在第二个测试实例验证组合行为，避免和双发样本混在一起
export OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=true

# 预览模式下继续使用现有 OTLP 导出配置，不把 Zipkin 当作回退出口
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
java $JAVA_TOOL_OPTIONS -jar orders-service.jar

重点检查三件事：第一，启动日志里是否出现 instrumentation 初始化或配置错误；第二，仪表盘、告警和下游查询是否仍能找到字段；第三，导出器是否符合当前预览边界。官方说明提到 Zipkin exporter 支持在预览模式中移除，已有 Zipkin 依赖应提前改成 OTLP 或经 Collector 转换。

按下游依赖决定是否扩大范围

如果是数据库场景，检查连接池指标从毫秒到秒的单位变化，并重新审视阈值；如果是消息场景，检查生产者和消费者的 span 是否仍按预期关联，尤其是 receive spans 和批处理；如果是日志场景，确认结构化字段选择器没有因通配符扩大采集范围。

推荐的回归顺序是：保存旧样本 → 双发比较 → 总开关启动 → 复查查询和告警 → 记录不能自动迁移的项 → 评估回滚。预览期间不要同时升级 agent、Collector、后端存储和仪表盘规则，否则出现差异时很难判断根因。

常见问题

2.32.0 能直接代表最终 3.0 吗？不能。它是 release candidate，官方明确提示正式发布前行为仍可能变化，应把结果当作迁移准备信号。

为什么字段名没变，告警还是失效？新版本可能改变字段值、类型或单位；例如阈值从毫秒切换到秒时，查询表达式需要同步换算。

双发和总开关要放在同一个实例吗？不建议。双发用于比较，总开关用于模拟新默认行为，分开部署更容易保存样本、定位差异和回滚。