Perubahan yang memutus kompatibilitas dan panduan migrasi ARMS Java agent v5.x - Application Real-Time Monitoring Service

Informasi versi

Java agent v5.x dibangun di atas OpenTelemetry Java Instrumentation dan konvensi semantik OTel, sebagaimana dijelaskan dalam Catatan Rilis Java Agent.

Peningkatan konvensi semantik

Versi 5.x sepenuhnya mengadopsi konvensi semantik OpenTelemetry (OTel), standar observabilitas de facto. OTel menyediakan format data yang ketat, terbuka, dan terus berkembang yang diadopsi oleh sebagian besar penyedia utama.

Sebagai kontributor utama OTel, Alibaba Cloud mengadopsi standar ini di v5.x untuk memberikan:

Data observabilitas terstandarisasi: Format data seragam dengan semantik yang jelas, interoperabel lintas vendor observabilitas.
Kompatibilitas ekosistem yang lebih baik: Terintegrasi dengan alat observabilitas open-source dan komersial utama melalui ekosistem OTel.
Evolusi berkelanjutan: Dukungan fitur berkelanjutan seiring pertumbuhan komunitas OTel.
Troubleshooting yang lebih akurat: Data terstandarisasi memungkinkan pemantauan dan diagnostik yang lebih tepat.

Penting: Karena peningkatan konvensi semantik ini, beberapa atribut rentang (span) dan perilaku telah berubah dari v4.x. Baca dokumen ini dengan cermat sebelum Anda melakukan upgrade.

Perubahan semantik terkait OTel

Perubahan pada atribut span OTel yang sudah tidak digunakan (deprecated)

Versi 5.x menghapus atribut yang telah dinyatakan deprecated oleh OTel. Berikut adalah beberapa atribut HTTP yang deprecated beserta penggantinya.

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

Daftar lengkap atribut yang deprecated tersedia dalam dokumen spesifikasi OTel berikut:

Atribut HTTP yang deprecated: HTTP semantic conventions.

Atribut database yang deprecated: Database semantic conventions.

Atribut RPC yang deprecated: RPC semantic conventions.

Atribut messaging yang deprecated: Messaging semantic conventions.

Perubahan semantik terkait Alibaba Cloud

Perubahan umum

Penyesuaian atribut span Aliyun

Atribut v4.x	Atribut v5.x	Deskripsi
`out.ids`	`destId`	Diganti nama. Nilai dan fungsi tidak berubah.
`component.name`	`call.type`	Diganti nama untuk kejelasan.
`rpc.type`	`rpcType`	Diganti ke camelCase. Nilai dan fungsi tidak berubah.
`serviceType`	Dihapus	Tidak lagi didukung.

Ini adalah atribut kustom Alibaba Cloud yang memperluas standar OTel. Deskripsi atribut asli tersedia di atribut span dan sumber daya agen v4.x.

Perubahan plugin HTTP

1. Perubahan format nama span klien HTTP

Sesuai spesifikasi OTel, Span Name klien HTTP menggunakan format {method} {target}, di mana {target} sesuai dengan atribut url.template. Karena sebagian besar komponen OTel hulu tidak mengumpulkan url.template, agen v5.x menggunakan url.full sebagai url.template secara default, menghasilkan nama span yang lebih deskriptif dibandingkan v4.x yang sering hanya menampilkan {method}.

Contoh perubahan:

Format v4.x: GET /get
Format v5.x: GET http://httpbin.org/get

2. Perubahan jumlah span Vert.x-Web

Di v5.x, Vert.x-Web tidak lagi merekam span terpisah. Sebagai gantinya, ia menetapkan http.route pada span server, sehingga mengurangi jumlah span sebanyak satu. Hal ini selaras dengan agen OTel hulu.

3. Perubahan pengumpulan http.route Spring Cloud Gateway

Versi 5.x menginstrumentasi Spring Cloud Gateway. Atribut http.route pada span server diatur ke route.id dari konfigurasi rute, dan nama span mengikuti format {METHOD} {route.id}.

Atribut	Perilaku v4.x	Perilaku v5.x
Span Name	`GET /api/user/123` (Menyertakan path lengkap, yang dapat menyebabkan kardinalitas tinggi.)	`GET user_service_route`
http.route	`/api/user/123` (Sama dengan http.path, dengan kardinalitas tidak terkendali.)	`user_service_route` (ID rute yang dikonfigurasi, yang memiliki kardinalitas rendah.)

Hal ini selaras dengan agen OTel hulu (opentelemetry-java-instrumentation#9597). Agen menggunakan route.id alih-alih pola path karena satu rute gateway dapat memiliki beberapa predikat path. route.id menyediakan pengenal stabil dengan kardinalitas rendah. Agen mengekstraksi Route yang cocok dari ServerWebExchange, memfilter ID yang dihasilkan otomatis (format UUID), dan hanya mengumpulkan ID rute yang dikonfigurasi secara eksplisit.

Perubahan plugin database

1. Penyesuaian atribut umum

Atribut v4.x	Atribut v5.x	Deskripsi
`db.name`	`destId`	Bidang-bidang ini digabung.
`sql`	`db.query.text`	Selaras dengan konvensi OTel.
`op.type`	`db.operation.name`	Selaras dengan konvensi OTel.
`db.bindValue`	`db.query.parameter.<index>`	Contoh: `db.query.parameter.0=value1`
`tableName`	Dihapus	Sebelumnya hanya dicatat untuk database relasional. Sekarang sudah tercakup dalam atribut `db.query.text`.

2. Perubahan plugin Redis dan Lettuce

Perubahan

Deskripsi

Atribut redis.args dihapus.

Untuk melihat parameter, nonaktifkan sanitizer dengan menyetel:

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

Atribut redis.command.key dihapus.

Mewakili argumen perintah pertama. Hanya terlihat saat sanitasi data dinonaktifkan.

3. Penghapusan response.size untuk Redis dan Elasticsearch

Atribut response.size dihapus di v5.x karena overhead pengumpulan yang tinggi.

4. Penangkapan parameter dan sanitasi SQL

Jika Anda mengaktifkan penangkapan parameter, sanitasi SQL akan dinonaktifkan. Perubahan ini memerlukan restart aplikasi.
Pengaturan pernyataan SQL mentah hanya memengaruhi jejak (trace). Perubahan ini memerlukan restart aplikasi.

5. Perubahan instrumentasi DruidDataSource.getConnection

Versi 4.x menggunakan instrumentasi khusus Druid untuk koneksi database. Versi 5.x menggunakan instrumentasi JDBC terpadu, selaras dengan agen OTel.

6. Aturan pengumpulan atribut endpoint

Atribut endpoint dibuat menggunakan urutan fallback berikut:

Menggabungkan server.address dan server.port dari konvensi semantik OTel.
Jika tidak tersedia, menggabungkan network.peer.address dan network.peer.port.
Jika tidak tersedia, fallback ke string koneksi.
Jika semua metode gagal, endpoint default menjadi Unknown.

Batasan yang diketahui:

Skenario	Dampak
Skenario pengecualian tertentu di Elasticsearch	Ketika tidak ada respons yang diterima (misalnya penolakan koneksi), server.address dan server.port tidak tersedia, sehingga endpoint ditampilkan sebagai `unknown`. Hal ini hanya memengaruhi tampilan dan tidak memengaruhi navigasi jejak.
Versi Lettuce sebelum 5.1 dan versi 6.0.0 hingga 6.0.9	Keterbatasan plugin mencegah pengumpulan server.address dan server.port, sehingga endpoint ditampilkan sebagai `unknown`. Hal ini hanya memengaruhi tampilan dan tidak memengaruhi navigasi jejak. Lakukan upgrade ke versi yang lebih baru untuk mengatasi masalah ini.

Perubahan plugin tugas terjadwal

1. Penyesuaian atribut span ElasticJob

Atribut v4.x	Atribut v5.x	Alasan perubahan
`job.result.status`	Dihapus	Dihapus. v5.x menggunakan kembali kode status span OTel.
`job.name`	`scheduling.apache-elasticjob.job.name`	Selaras dengan implementasi OTel.
`job.id`	`scheduling.apache-elasticjob.task.id`	Selaras dengan implementasi OTel.
`item`	`scheduling.apache-elasticjob.sharding.item.index`	Selaras dengan OTel. Nilai sekarang adalah indeks item saat ini.
`shardingItemParameters`	`scheduling.apache-elasticjob.sharding.item.parameter`	Selaras dengan OTel. Nilai sekarang adalah parameter untuk indeks item saat ini.
`shardingTotalCount`	`scheduling.apache-elasticjob.sharding.total.count`	Selaras dengan implementasi OTel.
-	`job.system`	Atribut baru yang selaras dengan implementasi OTel.

2. Penyesuaian atribut span penjadwalan Spring

Atribut v4.x	Atribut v5.x	Alasan perubahan
`job.id`	Dihapus	Informasi ini sekarang disediakan oleh atribut `code.namespace` dan `code.function` dari implementasi OTel.
`job.name`	Dihapus	Informasi ini sekarang disediakan oleh atribut `code.namespace` dan `code.function` dari implementasi OTel.
-	`job.system`	Atribut baru yang selaras dengan implementasi OTel.

3. Penyesuaian atribut span XXL-JOB

Atribut v4.x	Atribut v5.x	Alasan perubahan
`job.result.status`	Dihapus	Dihapus. v5.x menggunakan kembali kode status span OTel.
-	`scheduling.xxl-job.glue.type`	Atribut baru yang digunakan untuk membedakan jenis tugas.
-	`scheduling.xxl-job.job.id`	Atribut baru yang direkam untuk tugas jenis skrip.

4. Penyesuaian atribut span Quartz

Atribut v4.x	Atribut v5.x	Alasan perubahan
`job.result.status`	Dihapus	Dihapus. v5.x menggunakan kembali kode status span OTel.
`group.id`	Dihapus	Informasi ini sekarang termasuk dalam nama span.
`job.id`	Dihapus	Informasi ini sekarang termasuk dalam nama span.

Perubahan plugin RPC

Penyesuaian definisi error gRPC

Versi 5.x memperbaiki definisi error gRPC.

Peran	Perilaku v4.x	Perilaku v5.x
Client	Semua kode respons non-OK ditandai sebagai error.	Semua kode respons non-OK ditandai sebagai error (tidak berubah).
Server-side	Semua kode respons non-OK ditandai sebagai error.	Hanya enam kode status tertentu yang ditandai sebagai error di sisi server.

Detailnya tersedia di gRPC semantic conventions.

Perubahan plugin messaging

Di v4.x, pengumpulan tag fencing lingkungan otomatis dapat menyebabkan ambiguitas data. Versi 5.x tidak lagi mengumpulkan hal ini secara default. Properti sistem baru, otel.instrumentation.messaging.common.broker_identifier, mengontrol perilaku ini:

Perilaku v4.x

Perilaku v5.x

Deskripsi

producer destId

Default:

{brokerServerAddressList}@{Topic}

Dengan toggle dimatikan:

{Topic}

Contoh:

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

Default:

{Topic}

Dengan Environment Fencing diaktifkan:

{environment fencing tag}@{Topic}

Perubahan ini berlaku untuk plugin berikut, yang diinstrumentasi oleh OpenTelemetry:

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

Perilaku plugin berikut tetap sama seperti di v4.x:

ons-client
paho-mqtt
mns

producer endpoint

Default:

{brokerServerAddressList}

Dengan toggle dimatikan:

Unknown

Contoh:

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

Default:

Unknown

Dengan fencing lingkungan diaktifkan:

{environment fencing tag}

consumer destId

Default:

{brokerServerAddressList}

Dengan toggle dimatikan:

Unknown

Contoh:

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

Default:

Unknown

Dengan Environment Fence diaktifkan:

{environment fencing tag}

consumer endpoint

Default:

{brokerServerAddressList}@{Topic}

Dengan toggle dimatikan:

{Topic}

Contoh:

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

Default:

{Topic}

Dengan fencing lingkungan diaktifkan:

{environment fencing tag}@{Topic}

Perubahan konfigurasi dinamis

1. Toggle atribut spesifikasi OTel

Konfigurasi "Record OpenTelemetry specification convention attributes" diaktifkan secara default.

Peringatan: Di v5.x, toggle ini tidak dapat dinonaktifkan. Menonaktifkan konfigurasi ini mencegah agen mengumpulkan beberapa atribut span dan memengaruhi fitur navigasi halaman.

2. Konfigurasi "Maximum SQL statement length" dihapus

Agen OTel memberlakukan batas panjang SQL bawaan untuk mencegah kebocoran memori: 32 KB dalam mode sanitasi. Dalam mode non-sanitasi, kendalikan batas tersebut dengan parameter otel.attribute.value.length.limit.

Lainnya

Ko-deploy dengan agen lain

Java agent Alibaba Cloud tidak mendukung ko-deploy dengan agen lain, termasuk agen OTel open-source atau agen dari vendor lain seperti SkyWalking.