ARMS Java エージェント v5.x の破壊的変更と移行ガイド - Application Real-Time Monitoring Service

バージョン情報

Java エージェント v5.x は、Java エージェントリリースノートに詳述されているように、 OpenTelemetry Java インストルメンテーションと OTel セマンティック規約に基づいて構築されています。

セマンティック規約のアップグレード

バージョン 5.x は、事実上の可観測性標準である OpenTelemetry (OTel) セマンティック規約を完全に採用しています。OTel は、ほとんどの主要プロバイダーに採用されている、厳格でオープン、かつ継続的に進化するデータ形式を提供します。

OTel の主要なコントリビューターとして、Alibaba Cloud は v5.x でこの標準を採用し、以下を提供します：

標準化された可観測性データ：明確なセマンティクスを持つ統一されたデータ形式で、可観測性ベンダー間で相互運用できます。
強化されたエコシステムの互換性：OTel エコシステムを通じて、主流のオープンソースおよび商用の可観測性ツールと統合できます。
継続的な進化：OTel コミュニティの成長に伴い、継続的な機能サポートが利用可能になります。
より正確なトラブルシューティング：標準化されたデータにより、より正確なモニタリングと診断が可能になります。

重要：セマンティック規約のアップグレードにより、一部のスパン属性と動作が v4.x から変更されています。アップグレードする前に、このドキュメントをよくお読みください。

OTel 関連のセマンティック変更

非推奨となった OTel スパン属性の変更

バージョン 5.x では、OTel で非推奨となった属性を削除しました。以下は、非推奨となった 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

非推奨属性の完全なリストは、以下の OTel 仕様ドキュメントに記載されています。

非推奨の HTTP 属性：HTTP セマンティック規約

非推奨のデータベース属性：データベースセマンティック規約

非推奨の RPC 属性：RPC セマンティック規約

非推奨のメッセージング属性：メッセージングセマンティック規約

Alibaba Cloud のセマンティック変更

一般的な変更

Alibaba Cloud スパン属性の調整

v4.x の属性	v5.x の属性	説明
`out.ids`	`destId`	名称が変更されました。値と機能は変更ありません。
`component.name`	`call.type`	明確にするため、名称が変更されました。
`rpc.type`	`rpcType`	名称がキャメルケースに変更されました。値と機能は変更ありません。
`serviceType`	削除	サポートされなくなりました。

これらは、OTel 標準を拡張する Alibaba Cloud のカスタム属性です。元の属性の説明は、v4.x エージェントのスパン属性とリソースに記載されています。

HTTP プラグインの変更

1. HTTP クライアントのスパン名形式の変更

OTel 仕様に従い、HTTP クライアントの スパン名 は {method} {target} 形式を使用します。ここで {target} は url.template 属性に対応します。ほとんどのアップストリーム OTel コンポーネントは url.template を収集しないため、v5.x エージェントはデフォルトで url.full を url.template として使用します。これにより、{method} のみの表示が多かった v4.x と比べて、より説明的なスパン名になります。

変更例：

v4.x 形式： GET /get
v5.x 形式： GET http://httpbin.org/get

2. Vert.x-Web のスパン数の変更

v5.x では、Vert.x-Web は個別のスパンを記録しなくなりました。代わりに、サーバースパンに http.route を設定し、スパン数を 1 つ削減します。これはアップストリーム OTel エージェントと整合します。

3. Spring Cloud Gateway の http.route 収集の変更

バージョン 5.x は Spring Cloud Gateway をインストルメント化します。サーバースパンの http.route には、ルート設定の route.id が設定され、スパン名は {METHOD} {route.id} 形式に従います。

属性	v4.x の動作	v5.x の動作
スパン名	`GET /api/user/123` (完全なパスを含むため、高カーディナリティの原因となることがあります)	`GET user_service_route`
http.route	`/api/user/123` (http.path と同じで、カーディナリティが制御されません)	`user_service_route` (設定されたルート ID であり、低カーディナリティです)

これは、アップストリームの OTel エージェント (opentelemetry-java-instrumentation#9597) に準拠しています。エージェントは、単一のゲートウェイルートが複数のパス述語を持つことができるため、パスパターンの代わりに route.id を使用します。route.id は、安定した低カーディナリティの識別子を提供します。エージェントは ServerWebExchange から一致したルートを抽出し、自動生成された ID (UUID 形式) を除外し、明示的に設定されたルート ID のみを収集します。

データベースプラグインの変更

1. 一般的な属性の調整

v4.x 属性	v5.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 属性は削除されます。

パラメーターを確認するには、次の設定でサニタイザーを無効にしてください：

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

redis.command.key 属性は削除されました。

最初のコマンド引数を表します。データサニタイゼーションを無効にした場合にのみ表示されます。

3. Redis および Elasticsearch における response.size の削除

v5.x では、収集オーバーヘッドが高いため、response.size 属性は削除されています。

4. パラメーターキャプチャと SQL サニタイゼーション

パラメーターキャプチャを有効にすると、SQL サニタイゼーションは無効になります。この変更を反映するには、アプリケーションを再起動する必要があります。
生の SQL ステートメント表示の切り替えは、トレースにのみ影響します。この変更を反映するには、アプリケーションを再起動する必要があります。

5. DruidDataSource.getConnection インストルメンテーションの変更

バージョン 4.x では、データベース接続に Druid 固有のインストルメンテーションを使用していました。バージョン 5.x では、OTel エージェントに合わせて、統一された JDBC インストルメンテーションを使用します。

6. エンドポイント属性の収集ルール

endpoint属性は、以下のフォールバックシーケンスを使用して構築されます：

OTel セマンティック規約の server.address と server.port を連結します。
利用できない場合は、network.peer.address と network.peer.port を連結してください。
利用できない場合は、接続文字列にフォールバックします。
すべてのメソッドが失敗した場合、エンドポイントはデフォルトで Unknown になります。

既知の制限：

シナリオ	影響
Elasticsearch での特定の例外シナリオ	応答がない場合 (接続拒否など)、server.address と server.port は利用できないため、エンドポイントは `unknown` と表示されます。これは表示のみに影響し、トレースナビゲーションには影響しません。
Lettuce 5.1 より前のバージョン、およびバージョン 6.0.0～6.0.9	プラグインの制限により server.address と server.port を収集できないため、エンドポイントは `unknown` と表示されます。この影響は表示のみで、トレースナビゲーションには影響しません。これを解決するには、新しいバージョンにアップグレードしてください。

スケジュールされたタスクプラグインの変更

1. ElasticJob スパン属性の調整

v4.x 属性	v5.x 属性	変更理由
`job.result.status`	削除	削除されました。v5.x では OTel スパンステータスコードを再利用します。
`job.name`	`scheduling.apache-elasticjob.job.name`	OTel 実装に準拠しています。
`job.id`	`scheduling.apache-elasticjob.task.id`	OTel 実装に準拠しています。
`item`	`scheduling.apache-elasticjob.sharding.item.index`	OTel に準拠しています。値は現在のアイテムインデックスです。
`shardingItemParameters`	`scheduling.apache-elasticjob.sharding.item.parameter`	OTel に準拠しています。値は現在のアイテムインデックスのパラメーターです。
`shardingTotalCount`	`scheduling.apache-elasticjob.sharding.total.count`	OTel 実装に準拠しています。
-	`job.system`	OTel 実装に準拠した新しい属性です。

2. Spring スケジューリングスパン属性の調整

v4.x 属性	v5.x 属性	変更理由
`job.id`	削除	この情報は、OTel 実装の `code.namespace` および `code.function` 属性で示されるようになりました。
`job.name`	削除	この情報は、OTel 実装の `code.namespace` および `code.function` 属性で示されるようになりました。
-	`job.system`	OTel 実装に準拠した新しい属性です。

3. XXL-JOB スパン属性の調整

v4.x 属性	v5.x 属性	変更理由
`job.result.status`	削除	削除されました。v5.x では OTel スパンステータスコードを再利用します。
-	`scheduling.xxl-job.glue.type`	タスクタイプを区別するための新しい属性です。
-	`scheduling.xxl-job.job.id`	スクリプトタイプのタスク用に記録される新しい属性です。

4. Quartz スパン属性の調整

v4.x 属性	v5.x 属性	変更理由
`job.result.status`	削除	削除されました。v5.x では OTel スパンステータスコードを再利用します。
`group.id`	削除	この情報はスパン名に含まれるようになりました。
`job.id`	削除	この情報はスパン名に含まれるようになりました。

RPC プラグインの変更

gRPC エラー定義の調整

バージョン 5.x では、gRPC エラーの定義を調整します。

役割	v4.x の動作	v5.x の動作
クライアント	OK 以外のすべてのステータスコードはエラーと見なされます。	OK 以外のすべてのステータスコードはエラーと見なされます (変更なし)。
サーバーサイド	OK 以外のすべてのステータスコードはエラーと見なされます。	サーバーサイドでは、6 つの特定のステータスコードのみがエラーと見なされます。

詳細については、「gRPC セマンティック規約」をご参照ください。

メッセージングプラグインの変更

v4.x では、環境フェンシングタグの自動収集がデータの曖昧性を引き起こす可能性がありました。バージョン 5.x では、デフォルトではこれを収集しなくなりました。新しいシステムプロパティである otel.instrumentation.messaging.common.broker_identifier が、この挙動を制御します：

v4.x の挙動

v5.x の挙動

説明

プロデューサー destId

デフォルト：

{brokerServerAddressList}@{Topic}

トグルを無効にした場合：

{Topic}

例：

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

デフォルト：

{Topic}

環境フェンシングを有効にした場合：

{environment fencing tag}@{Topic}

この変更は、OpenTelemetry でインストルメントされる以下のプラグインに適用されます：

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

以下のプラグインの挙動は v4.x と同じです：

ons-client
paho-mqtt
mns

プロデューサーエンドポイント

デフォルト：

{brokerServerAddressList}

トグルを無効にした場合：

Unknown

例：

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

デフォルト：

Unknown

環境フェンシングを有効にした場合：

{environment fencing tag}

コンシューマー destId

デフォルト：

{brokerServerAddressList}

トグルがオフの場合:

不明

例：

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

デフォルト：

不明

環境フェンシングが有効な場合:

{環境フェンシングタグ}

コンシューマーエンドポイント

デフォルト：

{brokerServerAddressList}@{Topic}

トグルがオフの場合:

{トピック}

例：

[alikafka-post-cn-pe33gzedv005-1.alikafka.aliyuncs.com:9093,...]@お使いのトピック

デフォルト：

{トピック}

環境フェンシングが有効な場合：

{環境隔離タグ}@{トピック}

動的設定の変更

1. OTel 仕様属性のトグル

「OpenTelemetry 仕様規約属性を記録」設定は、デフォルトで有効になっています。

警告：v5.x では、このトグルは無効にできません。この設定を無効にすると、エージェントが一部のスパン属性を収集できなくなり、ページナビゲーション機能に影響を及ぼします。

2. 「SQL ステートメントの最大長」設定の削除

OTel エージェントは、メモリリークを防ぐため、サニタイズモードでは 32 KB の組み込み SQL 長制限を適用します。非サニタイズモードでは、otel.attribute.value.length.limit パラメーターで制限を制御します。

その他

他のエージェントとの共存

Alibaba Cloud Java エージェントは、オープンソースの OTel エージェント、または SkyWalking などの他ベンダー製エージェントとの共存をサポートしていません。