【产品变更】Java探针5.x 版本不兼容变更说明 - 应用实时监控服务ARMS

版本信息

Java Agent 5.x 版本依赖 OpenTelemetry Java Instrumentation 和 OpenTelemetry Semantic Conventions 进行实现，详情请参见探针（Java Agent）版本说明。

语义规范升级说明

5.x 版本全面采用 OpenTelemetry（简称 OTel）语义规范标准。OTel 语义规范是当前可观测领域的事实标准，吸引了全球几十家知名可观测厂商和数千名可观测领域专家参与建设和贡献，被国内外几乎所有主流可观测厂商所采纳。其语义标准的定义是严谨、完善、开放，并可持续发展和演进。

阿里云作为国内深度参与 OTel 语义标准建设和实现的厂商，在 Java 探针 5.x 版本中全面采用相关标准，为用户提供：

标准化的可观测数据：遵循国际标准，确保数据格式统一、语义清晰、能支持与其他可观测厂商间的数据格式互通。
更好的生态兼容性：基于OTel生态强大的可扩展性，较容易实现与主流开源工具和商业产品的无缝集成。
持续演进的能力：跟随 OTel 社区发展，持续获得新特性支持
更精准的问题定位：基于标准化的数据结构，提供更准确的监控和诊断能力

重要提示：由于语义规范的升级，部分 Span 属性和行为相较于 4.x 版本有所调整。请在使用前仔细阅读本文档。

OTel 相关语义变更

OTel Span deprecated（废弃）属性变更

5.x 版本移除了4.x中部分已被 OTel 标记为 deprecated 的相关属性，比如以下是部分 HTTP 的属性内容：

http.method → http.request.method
http.status_code → http.response.status_code
http.url → url.full
http.scheme → url.scheme
net.peer.name → server.address
net.peer.port → server.port

其他更多完整 Deprecated 属性变更请参考以下文档：

HTTP Deprecated 属性完整变更请参考文档

Database Deprecated 属性完整变更请参考文档

RPC Deprecated 属性完整变更请参考文档

Message Deprecated 属性完整变更请参考文档

Aliyun 相关语义变更

通用变更

Aliyun Span 属性调整

4.x 版本属性	5.x 版本属性	说明
`out.ids`	`destId`	两者无差别，直接替换
`component.name`	`call.type`	两者仅大小写区别
`rpc.type`	`rpcType`	两者无差别
`serviceType`	移除	不再支持

该部分内容部署于OTel可观测语义标准定义字段，是阿里云在OTel基础上为丰富产品功能所引入的自定义语义字段。相关字段描述参见4.x探针Span Attributes/Resources说明文档。

HTTP 插件变更

1. HTTP Client Span Name 格式变更

根据 OTel 规范，HTTP Client 的 Span Name 由 {method} {target} 构造，其中 {target} 对应 url.template 属性，由于url.template字段在上游OTel探针中在大部分组件下暂时无法采集，5.x探针在 OTel 探针基础上，默认会把url.full作为url.template去构建一个更丰富的 Span Name，避免仅包含{method}的 HTTP Client Span Name 影响用户使用体验，相比于4.x，其信息会更丰富。

变更影响示例：

4.x 格式：GET /get
5.x 格式：GET http://httpbin.org/get

2. Vert.x-Web Span 数量变更

5.x版本中，为避免重复，Vert.x-Web 框架不再记录单独的Span，仅负责对Server Span采集设置 http.route，因此相比 4.x 会减少一个 Span，此行为与 OTel 上游探针保持一致。

数据库插件变更

1. 通用属性调整

4.x 版本属性	5.x 版本属性	说明
`db.name`	`destId`	字段合并
`sql`	`db.query.text`	遵循 OTel 规范
`op.type`	`db.operation.name`	遵循 OTel 规范
`db.bindValue`	`db.query.parameter.<index>`	格式示例：`db.query.parameter.0=value1`
`tableName`	移除	仅关系性数据库记录了该字段，请在`db.query.text`中查看相关内容

2. Redis/Lettuce 插件变更

变更项

说明

redis.args 字段移除

如需查看插件相关参数，可通过关闭 sanitizer 功能：

otel.instrumentation.common.db-statement-sanitizer.enabled=false

redis.command.key 字段移除

该字段为命令的第一个参数，需关闭信息隐匿功能才能获取

3. Redis/ElasticSearch response.size 字段移除

response.size 字段由于采集开销较大，5.x 版本不再支持采集。

4. 参数捕获与 SQL 脱敏说明

开启捕获参数会使 SQL 语句脱敏失效（重启生效）。
SQL 原文开关仅对调用链生效（重启生效）。

5. Span Name为 DruidDataSource.getConnection 的数据库连接获取的埋点实现变更

数据库连接获取的埋点采集有所调整，4.x基于Druid埋点实现，5.x跟OTel探针实现保持一致，基于JDBC统一埋点实现。

6. Endpoint 字段采集规则

Span 中 endpoint 字段的采集调整与构造原则：

基于OTel语义中的 server.address : server.port 拼接。
若不存在，基于OTel语义中的 network.peer.address : network.peer.port 拼接。
若不存在，数据库插件会 fallback 到连接串。
若仍无法获取，显示为 Unknown。

已知限制：

场景	影响
ElasticSearch 特定异常场景	无 response 时（如 connection refused）无法获取 server.address/port，显示 `unknown`，只影响展示，不影响指标跳转调用链
Lettuce 5.1 以下、6.0.0~6.0.9 版本	由于插件限制无法获取 server.address/port，显示 `unknown`，只影响展示，不影响指标跳转调用链，建议升级

定时任务插件变更

1. ElasticJob Span Attributes 调整

4.x 版本	5.x 版本	变更原因
`job.result.status`	移除	复用 OTel Span StatusCode
`job.name`	`scheduling.apache-elasticjob.job.name`	遵循 OTel 实现
`job.id`	`scheduling.apache-elasticjob.task.id`	遵循 OTel 实现
`item`	`scheduling.apache-elasticjob.sharding.item.index`	遵循 OTel 实现，内容改为当前 item 索引
`shardingItemParameters`	`scheduling.apache-elasticjob.sharding.item.parameter`	遵循 OTel 实现，内容改为当前 item 索引对应参数值
`shardingTotalCount`	`scheduling.apache-elasticjob.sharding.total.count`	遵循 OTel 实现
-	`job.system`	新增，遵循 OTel 实现

2. Spring Scheduling Span Attributes 调整

4.x 版本	5.x 版本	变更原因
`job.id`	移除	OTel 实现中 `code.namespace` + `code.function` 已包含相关含义
`job.name`	移除	OTel 实现中 `code.namespace` + `code.function` 已包含相关含义
-	`job.system`	新增，遵循 OTel 实现

3. XXL-JOB Span Attributes 调整

4.x 版本	5.x 版本	变更原因
`job.result.status`	移除	复用 OTel Span StatusCode
-	`scheduling.xxl-job.glue.type`	新增，用于区分任务类型
-	`scheduling.xxl-job.job.id`	新增，Script 类型任务时记录

4. Quartz Span Attributes 调整

4.x 版本	5.x 版本	变更原因
`job.result.status`	移除	复用 OTel Span StatusCode
`group.id`	移除	相关字段在 SpanName 中存在
`job.id`	移除	相关字段在 SpanName 中存在

RPC 插件变更

gRPC 错误定义调整

5.x 版本对 gRPC 错误的定义进行了细化：

角色	4.x 行为	5.x 行为
客户端	所有非 OK 响应码标记为异常	所有非 OK 响应码标记为异常（无变化）
服务端	所有非 OK 响应码标记为异常	仅特定 6 种状态码标记为异常

详细规范请参考：gRPC Semantic Conventions

消息插件变更

4.x中自动参数的环境隔离标签信息，在一些场景可能会造成数据混淆，在5.x中不再默认采集环境隔离标签信息，5.x中引入一个新的配置：otel.instrumentation.messaging.common.broker_identifier，可以通过 system properties 进行配置。采集行为是：

4.x版本

5.x版本

说明

生产者 destId

默认：

{brokerServerAddressList}@{Topic}

关闭开关：

{Topic}

示例：

[alikafka-post-cn-pe33gzedv005-1.alikafka.aliyuncs.com:9093,alikafka-post-cn-pe33gzedv005-2.alikafka.aliyuncs.com:9093,alikafka-post-cn-pe33gzedv005-3.alikafka.aliyuncs.com:9093]@YourTopic

默认：

{Topic}

配置环境隔离开关：

{隔离标签}@{Topic}

该变化发生在以下插件中（OpenTelemetry 已有的插件）：

rocketmq-client
rabbitmq
spring-rabbit
kafka-clients
spring-kafka
jms

以下插件目前行为不变（与 4.x 保持一致）：

ons-client
paho-mqtt
mns

生产者 endpoint

默认：

{brokerServerAddressList}

关闭开关：

Unknown

示例：

[alikafka-post-cn-pe33gzedv005-1.alikafka.aliyuncs.com:9093,alikafka-post-cn-pe33gzedv005-2.alikafka.aliyuncs.com:9093,alikafka-post-cn-pe33gzedv005-3.alikafka.aliyuncs.com:9093]

默认：

Unknown

配置环境隔离开关：

{隔离标签}

消费者 destId

默认：

{brokerServerAddressList}

关闭开关：

Unknown

示例：

[alikafka-post-cn-pe33gzedv005-1.alikafka.aliyuncs.com:9093,alikafka-post-cn-pe33gzedv005-2.alikafka.aliyuncs.com:9093,alikafka-post-cn-pe33gzedv005-3.alikafka.aliyuncs.com:9093]

默认：

Unknown

配置环境隔离开关：

{隔离标签}

消费者 endpoint

默认：

{brokerServerAddressList}@{Topic}

关闭开关：

{Topic}

示例：

[alikafka-post-cn-pe33gzedv005-1.alikafka.aliyuncs.com:9093,alikafka-post-cn-pe33gzedv005-2.alikafka.aliyuncs.com:9093,alikafka-post-cn-pe33gzedv005-3.alikafka.aliyuncs.com:9093]@YourTopic

默认：

{Topic}

配置环境隔离开关：

{隔离标签}@{Topic}

动态配置项变更

1. OTel Specification Attributes 开关说明

"记录 OpenTelemetry Specification 约定 attributes" 配置项默认开启。

警告：在5.x中该开关不再支持关闭，关闭此配置会导致部分 Span 属性无法获取，影响页面跳转功能。

2. 不再支持"SQL 语句最大长度"配置项

OTel 已内置 SQL 语句长度缓存限制，可规避内存泄漏问题，Sanitization 模式下 SQL 最大长度为 32KB，非 Sanitization 模式下可通过 otel.attribute.value.length.limit 参数控制。

其他

暂不支持跟其他探针同时使用

不支持与OTel开源版本或者其他探针（如SkyWalking）同时使用。