【產品變更】Java探針5.x 版本不相容變更說明 - Application Real-Time Monitoring Service

版本資訊

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）同時使用。