OpenTelemetry Java agent 把 2.32.0 当 3.0 预览，看板告警可能先失效

OpenTelemetry Java agent 2.32.0（2026-10-03 发布）已被官方当作 3.0 的候选版；3.0 仍计划在 2026 年 10 月落地。Jay DeLuca 在 2026-10-06 的官博里写明：3.0 会改默认遥测、配置和插桩行为，数据库与代码语义约定将变成稳定默认，消息系统会切到仍属实验的新约定。若你在 Spring Boot 上靠 -javaagent 出数，现在就该在测试环境走两步预览，否则 3.0 一上，看板查询和告警阈值很容易对不上。

两步预览怎么开

声明式配置（-Dotel.config.file=/path/to/otel-config.yaml）在 Java agent 里仍是实验状态。官博示例以环境变量为主。

第一步：总开关关掉，新旧属性双发。 在测试部署先采一份基线遥测，再按应用相关域追加 /dup（支持双发的指标也会一起出）：

OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=false
OTEL_SEMCONV_STABILITY_OPT_IN=database/dup,code/dup
OTEL_SEMCONV_STABILITY_PREVIEW=messaging/dup

对应系统属性大致为 otel.instrumentation.common.v3-preview、otel.semconv-stability.opt-in、otel.semconv-stability.preview。OPT_IN 与 PREVIEW 取值可逗号分隔；消息域在官博示例里走的是 OTEL_SEMCONV_STABILITY_PREVIEW=messaging/dup，数据库与代码走 OTEL_SEMCONV_STABILITY_OPT_IN。

双发不会保住每一项旧指标，也不会同时给出两套 span 名与 kind：连接池指标即使开了 database/dup 也会换新名和新单位；span 仍只有一个名字和一种 kind，/dup 对它们采用新约定。对照时要看属性、指标名、单位和链路形状。

第二步：打开总开关一起测。

OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=true

总开关会启用较新的数据库、代码与消息约定，并关掉这些域的 /dup。启动后核对字段是否还在、span/指标是否缺失，以及看板告警在去掉旧字段后是否仍可用。若分不清是约定问题还是默认值问题，可关掉总开关，并去掉第一步里的 /dup，只测新约定本身。

数据库与代码属性会怎么变

官博以 PostgreSQL JDBC、库名 orders、schema public 为例，双发时同一条 span 可同时带旧名与新名（db.namespace 的值形如 orders|public）：

旧属性	新属性（示例值）
`db.system: "postgresql"`	`db.system.name: "postgresql"`
`db.name: "orders"`	`db.namespace`（示例值 `orders` + 竖线 + `public`）
`db.statement: "SELECT * FROM orders"`	`db.query.text: "SELECT * FROM orders"`

此外还要改查询里的值、名、单位：

db.system: "mssql" → db.system.name: "microsoft.sql_server"
db.client.connections.max → db.client.connection.limit（只把 connections 改成 connection 不够）
连接池时长类指标：毫秒改为秒；开了 database/dup 也照样换名换单位，告警阈值要换算
code.namespace + code.function → code.function.name

server.address 表示配置的目标，network.peer.address（若有）表示实际连上的端点；集群场景下配置目标可能是端点列表。按 server.address 分组的服务图与看板，分组结果可能变，尽管属性名没变。更细的迁移说明见官方 Database semantic convention stability migration guide。

消息与 Kafka：名字、kind、父子关系

消息语义约定从 v1.24 升到 v1.43，在预览路径里仍属实验。Kafka span 名把操作放到前面：

操作	旧 span 名	预览 span 名
发送	`orders publish`	`send orders`
接收	`orders receive`	`poll orders`
处理	`orders process`	`process orders`

旧的 messaging.operation 会拆成 messaging.operation.name 与 messaging.operation.type（例如 Kafka poll：name=poll，type=receive）。poll span 的 kind 从 CONSUMER 变为 CLIENT。

单条消息、生产者上下文已写入消息时，父节点规则会变。官博要点：

默认不开 receive span、且没有活动 span：process 仍可挂在 send 下，并额外 link 到 send
不开 receive span，但处理发生在另一个活动 span 内（例如 @WithSpan、定时任务 span）：process 的父节点变成该活动 span，只通过 link 连生产者
打开 receive span、且消费者侧没有活动 span：预览里 process 可成为 send 的子节点并同属一条 trace；poll 单独表示客户端操作

批量 process 可 link 多条消息，不套用上述单条父模型。Receive span 仍是可选；2.32.0 下 Kafka 打开 receive 遥测还会打开 poll 时长指标。Kafka 不会因 messaging/dup 双发两套指标：它拿到的是预览侧仪器，本来就不发官博表格里那批旧 messaging 指标。

采集默认值与身份字段

打开总开关后，默认行为还会动几处：

应用已通过 SLF4J 键值对挂在日志上的结构化字段，可自动进入导出的日志属性；MDC 仍需单独开启
统一的 .included / .excluded 选择器（例如 OTEL_INSTRUMENTATION_COMMON_LOGGING_STRUCTURED_ATTRIBUTES_INCLUDED）取代旧的按源配置；支持 glob，写 * 表示采全部字段
Hibernate、Hystrix、Twilio 插桩默认关闭，需要则显式打开
预览模式移除 Zipkin exporter，改走 OTLP；仍配 Zipkin 时 agent/SDK 初始化会失败
身份：enduser.id → user.name，enduser.role（逗号分隔字符串）→ user.roles（字符串数组）；enduser.scope 不再采集。旧的 otel.instrumentation.common.enduser.*.enabled 在总开关打开后会被忽略，需改用 otel.instrumentation.common.user.name.enabled / user.roles.enabled
扩展与发行版维护者：invokedynamic 插桩成为默认，会改变插桩与 helper 类的加载方式

和 Spring Boot 读者相关的边界

本文读者假定你继续用 -javaagent（OpenTelemetry 文档也把这条路径列为 Spring Boot 的默认推荐）。

关于 OpenTelemetry Spring Boot starter，以及 Spring Boot 自带的 Micrometer + OTLP（management.otlp.metrics.export.* 等）是否会随本次 javaagent 预览开关发生同等的数据库/消息/默认插桩变化：在官博、OTel Spring Boot starter 文档与 Spring Boot Actuator 文档中未查到明确对照说明，记为未确认。PR #19400 表明 Zipkin 在 v3-preview 下的拒绝逻辑落在共享的 sdk-autoconfigure-support（同时被 javaagent 与 spring-boot-autoconfigure 依赖），但这不足以推断 starter 或 Boot 自带 Micrometer/OTLP 会完整复刻 agent 预览的遥测变更。若你主要走 Boot 自带 Micrometer/OTLP 而非 agent 插桩，请单独对照各自文档，不要默认套用本文的环境变量路径。

CHANGELOG / release notes 里还有大量 2.32.0 的弃用项与库级增强（例如 messaging headers 选择器迁移、结构化日志 .included 统一等）；与 3.0 预览总开关相关的迁移，以官博「Try the preview」与「What to check」为准。