ARMS Java agent v5.x breaking changes and migration guide - Application Real-Time Monitoring Service

Sürüm bilgileri

Java agent v5.x, Java Agent Sürüm Notları dokümanında ayrıntılı olarak açıklandığı gibi OpenTelemetry Java Instrumentation ve OTel anlamsal kuralları üzerine inşa edilmiştir.

Anlamsal kural yükseltmesi

5.x sürümü, fiili gözlemlenebilirlik standardı olan OpenTelemetry (OTel) anlamsal kurallarını tamamen benimser. OTel, çoğu büyük sağlayıcı tarafından benimsenen titiz, açık ve sürekli gelişen bir veri formatı sunar.

Önde gelen bir OTel katkıda bulunanı olarak Alibaba Cloud, bu standardı v5.x'te şu avantajları sunmak için uygular:

Standartlaştırılmış gözlemlenebilirlik verileri: Net anlamlara sahip, gözlemlenebilirlik satıcıları arasında birlikte çalışabilir üniform veri formatı.
Gelişmiş ekosistem uyumluluğu: OTel ekosistemi aracılığıyla başlıca açık kaynak ve ticari gözlemlenebilirlik araçlarıyla entegrasyon.
Sürekli evrim: OTel topluluğu büyüdükçe devam eden özellik desteği.
Daha hassas sorun giderme: Standartlaştırılmış veriler daha doğru izleme ve tanılama olanağı sağlar.

Important : Anlamsal kural yükseltmesi nedeniyle bazı span nitelikleri ve davranışları v4.x'ten farklıdır. Yükseltme işleminden önce bu dokümanı dikkatlice okuyun.

OTel ile ilgili anlamsal değişiklikler

Kullanım dışı bırakılan OTel span niteliklerinde yapılan değişiklikler

5.x sürümü, OTel tarafından kullanım dışı bırakılan nitelikleri kaldırır. Aşağıda, kullanım dışı bırakılan bazı HTTP nitelikleri ve bunların yerine geçenler listelenmiştir.

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

Kullanım dışı bırakılan niteliklerin tam listeleri aşağıdaki OTel spesifikasyon belgelerinde yer almaktadır:

Kullanım dışı bırakılan HTTP nitelikleri: HTTP semantic conventions .

Kullanım dışı bırakılan veritabanı nitelikleri: Database semantic conventions .

Kullanım dışı bırakılan RPC nitelikleri: RPC semantic conventions .

Kullanım dışı bırakılan mesajlaşma nitelikleri: Messaging semantic conventions .

Alibaba Cloud ile ilgili anlamsal değişiklikler

Genel değişiklikler

Aliyun span niteliği ayarlamaları

v4.x niteliği	v5.x niteliği	Açıklama
`out.ids`	`destId`	Yeniden adlandırıldı. Değer ve işlev değiştirilmedi.
`component.name`	`call.type`	Daha net olması için yeniden adlandırıldı.
`rpc.type`	`rpcType`	camelCase biçimine göre yeniden adlandırıldı. Değer ve işlev değiştirilmedi.
`serviceType`	Kaldırıldı	Artık desteklenmiyor.

Bunlar, OTel standardını genişleyen özel Alibaba Cloud nitelikleridir. Orijinal nitelik açıklamaları için v4.x agent span nitelikleri ve kaynakları kaynağına bakın.

HTTP eklentisi değişiklikleri

1. HTTP istemci span adı formatı değişikliği

OTel spesifikasyonuna göre, bir HTTP istemci Span Name öğesi {method} {target} formatını kullanır; burada {target} url.template niteliğine karşılık gelir. Çoğu upstream OTel bileşeni url.template bilgisini toplamadığından, v5.x agent varsayılan olarak url.full değerini url.template olarak kullanır. Bu durum, genellikle yalnızca {method} gösteren v4.x'e kıyasla daha açıklayıcı span adları üretir.

Değişiklik örneği:

v4.x formatı: GET /get
v5.x formatı: GET http://httpbin.org/get

2. Vert.x-Web span sayısı değişikliği

v5.x'te Vert.x-Web artık ayrı bir span kaydetmez. Bunun yerine, sunucu span üzerinde http.route değerini ayarlar ve span sayısını bir azaltır. Bu durum, upstream OTel agent ile uyumludur.

3. Spring Cloud Gateway http.route toplama değişikliği

5.x sürümü Spring Cloud Gateway'i enstrümantize eder. Sunucu span'inin http.route değeri, rota yapılandırmasındaki route.id olarak ayarlanır ve span adı {METHOD} {route.id} formatını takip eder.

Nitelik	v4.x davranışı	v5.x davranışı
Span Adı	`GET /api/user/123` (Yüksek kardinaliteye neden olabilen tam yolu içerir.)	`GET user_service_route`
http.route	`/api/user/123` (Kontrolsüz kardinalite ile http.path ile aynı.)	`user_service_route` (Düşük kardinaliteli yapılandırılmış rota kimliği.)

Bu durum, upstream OTel agent ile uyumludur (opentelemetry-java-instrumentation#9597). Agent, tek bir gateway rotasının birden fazla yol yüklemi içerebilmesi nedeniyle yol kalıpları yerine route.id kullanır. route.id kararlı ve düşük kardinaliteli bir tanımlayıcı sağlar. Agent, eşleşen Rotayı ServerWebExchange üzerinden çıkarır, otomatik oluşturulan kimlikleri (UUID formatı) filtreler ve yalnızca açıkça yapılandırılmış rota kimliklerini toplar.

Veritabanı eklentisi değişiklikleri

1. Genel nitelik ayarlamaları

v4.x niteliği	v5.x niteliği	Açıklama
`db.name`	`destId`	Bu alanlar birleştirildi.
`sql`	`db.query.text`	OTel kuralına uygun hale getirildi.
`op.type`	`db.operation.name`	OTel kuralına uygun hale getirildi.
`db.bindValue`	`db.query.parameter.<index>`	Örnek: `db.query.parameter.0=value1`
`tableName`	Kaldırıldı	Daha önce yalnızca ilişkisel veritabanları için kaydedilirdi. Artık `db.query.text` niteliği kapsamında ele alınmaktadır.

2. Redis ve Lettuce eklentisi değişiklikleri

Değişiklik

Açıklama

redis.args niteliği kaldırıldı.

Parametreleri görüntülemek için temizleyiciyi aşağıdaki ayarla devre dışı bırakın:

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

redis.command.key niteliği kaldırıldı.

İlk komut bağımsız değişkenini temsil eder. Yalnızca veri temizleme devre dışı bırakıldığında görünür.

3. Redis ve Elasticsearch için response.size kaldırılması

Yüksek toplama ek yükü nedeniyle response.size niteliği v5.x'te kaldırıldı.

4. Parametre yakalama ve SQL temizleme

Parametre yakalamayı etkinleştirirseniz SQL temizleme devre dışı bırakılır. Bu değişiklik uygulama yeniden başlatma gerektirir.
Ham SQL deyimi geçişi yalnızca izlemeleri etkiler. Bu değişiklik uygulama yeniden başlatma gerektirir.

5. DruidDataSource.getConnection enstrümantasyonunda yapılan değişiklik

4.x sürümü veritabanı bağlantıları için Druid'e özgü enstrümantasyon kullanıyordu. 5.x sürümü, OTel agent ile uyumlu olacak şekilde birleşik JDBC enstrümantasyonu kullanır.

6. Uç nokta niteliği toplama kuralları

endpoint niteliği aşağıdaki yedekleme sırası kullanılarak oluşturulur:

OTel anlamsal kuralından server.address ve server.port değerlerini birleştirin.
Mevcut değilse network.peer.address ve network.peer.port değerlerini birleştirin.
Hala mevcut değilse bağlantı dizesine geri dönün.
Tüm yöntemler başarısız olursa uç nokta varsayılan olarak Unknown olur.

Bilinen sınırlamalar:

Senaryo	Etki
Elasticsearch'teki belirli istisna senaryoları	Yanıt alınamadığında (bağlantı reddi gibi) server.address ve server.port mevcut olmadığından uç nokta `unknown` olarak gösterilir. Bu durum yalnızca görüntülemeyi etkiler ve izleme navigasyonunu etkilemez.
5,1'den eski Lettuce sürümleri ve 6.0.0 ile 6.0.9 arasındaki sürümler	Eklenti sınırlamaları nedeniyle server.address ve server.port toplanamaz, bu nedenle uç nokta `unknown` olarak gösterilir. Bu durum yalnızca görüntülemeyi etkiler ve izleme navigasyonunu etkilemez. Bu sorunu çözmek için daha yeni bir sürüme yükseltin.

Zamanlanmış görev eklentisi değişiklikleri

1. ElasticJob span niteliği ayarlamaları

v4.x niteliği	v5.x niteliği	Değişiklik nedeni
`job.result.status`	Kaldırıldı	Kaldırıldı. v5.x, OTel span durum kodunu yeniden kullanır.
`job.name`	`scheduling.apache-elasticjob.job.name`	OTel uygulamasına uygun hale getirildi.
`job.id`	`scheduling.apache-elasticjob.task.id`	OTel uygulamasına uygun hale getirildi.
`item`	`scheduling.apache-elasticjob.sharding.item.index`	OTel'e uygun hale getirildi. Değer artık geçerli öğe dizinidir.
`shardingItemParameters`	`scheduling.apache-elasticjob.sharding.item.parameter`	OTel'e uygun hale getirildi. Değer artık geçerli öğe dizini için parametredir.
`shardingTotalCount`	`scheduling.apache-elasticjob.sharding.total.count`	OTel uygulamasına uygun hale getirildi.
-	`job.system`	OTel uygulamasına uygun yeni nitelik.

2. Spring scheduling span niteliği ayarlamaları

v4.x niteliği	v5.x niteliği	Değişiklik nedeni
`job.id`	Kaldırıldı	Bu bilgiler artık OTel uygulamasından gelen `code.namespace` ve `code.function` nitelikleri tarafından sağlanmaktadır.
`job.name`	Kaldırıldı	Bu bilgiler artık OTel uygulamasından gelen `code.namespace` ve `code.function` nitelikleri tarafından sağlanmaktadır.
-	`job.system`	OTel uygulamasına uygun yeni nitelik.

3. XXL-JOB span niteliği ayarlamaları

v4.x niteliği	v5.x niteliği	Değişiklik nedeni
`job.result.status`	Kaldırıldı	Kaldırıldı. v5.x, OTel span durum kodunu yeniden kullanır.
-	`scheduling.xxl-job.glue.type`	Görev türlerini ayırt etmek için kullanılan yeni nitelik.
-	`scheduling.xxl-job.job.id`	Script tipi görevler için kaydedilen yeni nitelik.

4. Quartz span niteliği ayarlamaları

v4.x niteliği	v5.x niteliği	Değişiklik nedeni
`job.result.status`	Kaldırıldı	Kaldırıldı. v5.x, OTel span durum kodunu yeniden kullanır.
`group.id`	Kaldırıldı	Bu bilgiler artık span adına dahil edilmiştir.
`job.id`	Kaldırıldı	Bu bilgiler artık span adına dahil edilmiştir.

RPC eklentisi değişiklikleri

gRPC hata tanımı ayarlaması

5.x sürümü gRPC hatalarının tanımını iyileştirir.

Rol	v4.x davranışı	v5.x davranışı
İstemci	Tüm OK olmayan yanıt kodları hata olarak işaretlenir.	Tüm OK olmayan yanıt kodları hata olarak işaretlenir (değişiklik yok).
Sunucu tarafı	Tüm OK olmayan yanıt kodları hata olarak işaretlenir.	Sunucu tarafında yalnızca altı belirli durum kodu hata olarak işaretlenir.

Ayrıntılar için gRPC semantic conventions kaynağına bakın.

Mesajlaşma eklentisi değişiklikleri

v4.x'te otomatik ortam ayırma etiketi toplama işlemi veri belirsizliğine neden olabiliyordu. v5.x bunu varsayılan olarak artık toplamaz. Yeni bir sistem özelliği olan otel.instrumentation.messaging.common.broker_identifier bu davranışı kontrol eder:

v4.x davranışı

v5.x davranışı

Açıklama

producer destId

Varsayılan:

{brokerServerAddressList}@{Topic}

Geçiş kapalıyken:

{Topic}

Örnek:

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

Varsayılan:

{Topic}

Ortam ayırma etkinleştirildiğinde:

{environment fencing tag}@{Topic}

Bu değişiklik, OpenTelemetry tarafından enstrümantize edilen aşağıdaki eklentiler için geçerlidir:

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

Aşağıdaki eklentilerin davranışı v4.x ile aynı kalmıştır:

ons-client
paho-mqtt
mns

producer endpoint

Varsayılan:

{brokerServerAddressList}

Geçiş kapalıyken:

Unknown

Örnek:

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

Varsayılan:

Unknown

Ortam ayırma etkinleştirildiğinde:

{environment fencing tag}

consumer destId

Varsayılan:

{brokerServerAddressList}

Geçiş kapalıyken:

Unknown

Örnek:

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

Varsayılan:

Unknown

Ortam ayırma etkinleştirildiğinde:

{environment fencing tag}

consumer endpoint

Varsayılan:

{brokerServerAddressList}@{Topic}

Geçiş kapalıyken:

{Topic}

Örnek:

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

Varsayılan:

{Topic}

Ortam ayırma etkinleştirildiğinde:

{environment fencing tag}@{Topic}

Dinamik yapılandırma değişiklikleri

1. OTel spesifikasyon nitelikleri geçişi

"OpenTelemetry spesifikasyon kuralı niteliklerini kaydet" yapılandırması varsayılan olarak etkindir.

Warning : v5.x'te bu geçiş devre dışı bırakılamaz. Bu yapılandırmayı devre dışı bırakmak agent'ın bazı span niteliklerini toplamasını engeller ve sayfa navigasyon özelliklerini etkiler.

2. "Maksimum SQL deyimi uzunluğu" yapılandırmasının kaldırılması

OTel agent, bellek sızıntılarını önlemek için yerleşik bir SQL uzunluğu sınırı uygular: Temizleme modunda 32 KB. Temizleme olmayan modda limiti otel.attribute.value.length.limit parametresi ile kontrol edin.

Diğer

Diğer agent'larla birlikte dağıtım

Alibaba Cloud Java agent, açık kaynak OTel agent veya SkyWalking gibi diğer satıcıların agent'ları dahil olmak üzere diğer agent'larla birlikte dağıtımı desteklemez.