Grafana trace linkage: trace’ten veritabanı sorgusuna tek tıkla geçiş

Grafana Labs, Grafana Cloud’daki Database Observability uygulamasında trace linkage özelliğini genel kullanıma (GA) açtı. Özellik, OpenTelemetry ile instrument edilmiş uygulamaların database span’larını Alloy ile toplanan sorgu verisine bağlıyor. Eşleştirme sorgu metniyle veya sqlcommenter’ın SQL yorumuna eklediği trace ID ve span ID ile yapılıyor.

sqlcommenter nedir, ne için kullanılır?

sqlcommenter, uygulamanın gönderdiği SQL ifadelerine bağlam bilgisini yorum olarak ekleyen açık kaynak bir kütüphane ailesidir. Genellikle trace context, framework veya route gibi bilgileri sorgu metnine taşımak için kullanılır. Böylece veritabanı log’larında görünen bir sorgu, onu üreten uygulama isteğiyle ilişkilendirilebilir. Proje OpenTelemetry topluluğuna bağışlanmıştır.

Grafana Alloy nedir, ne için kullanılır?

Grafana Alloy, Grafana Labs’in OpenTelemetry uyumlu telemetri toplayıcısıdır. Metric, log ve trace verisini toplayıp işleyerek Grafana Cloud veya kendi kurduğunuz backend’lere gönderir. Database Observability senaryosunda veritabanına bağlanıp sorgu örneklerini toplar. Benzer işi yapan alternatifler arasında OpenTelemetry Collector bulunur.

Trace linkage hangi adımı kısaltıyor

Yavaş bir request’in trace’inde database span’ını görmek kolay. O span’ın arkasındaki çalıştırmayı veritabanında bulmak için çoğu zaman timestamp’leri elle eşleştirmeniz gerekiyor. Trace linkage bu adımı tek tıka indiriyor. Span’daki sorgu metnine tıklayınca Database Observability’de o sorgunun örnek çalıştırmalarına, geçmiş performansına, schema’sına ve explain plan’ine geçiyorsunuz.

Duyuru Grafana Cloud’a özgü. Grafana Cloud Traces ile Database Observability’yi birlikte kullanıyorsanız özelliğin işinize yaraması için ek bir ürün gerekmiyor. Self-hosted Tempo için Grafana bir şey söylemiyor.

İki eşleştirme yolu, iki farklı kesinlik

• Sorgu metni eşleştirme: span’daki db.query.text veya eski adıyla db.statement, database system ve database name kullanılıyor. Uygulama kodunda değişiklik gerekmiyor. Sonuç o sorgunun genel örnekleri ve geçmişi oluyor, belirli bir çalıştırma değil.
• Sqlcommenter ile traceparent eşleştirme: trace ID ve span ID, SQL ifadesinin sonuna yorum olarak ekleniyor. Alloy bileşeni bu yorumu okuyup query sample log’larına yazıyor. Böylece span’dan tek bir çalıştırmaya iniyorsunuz.

İkinci yol da kesin sonuç garanti etmiyor. Alloy veritabanını aralıklarla yokluyor; çok kısa süren bir sorgu iki yoklama arasında kaçabilir. Eşleşme bulunamadığında bunu “sorgu hiç çalışmadı” diye okumayın.

Önce mevcut instrumentation’a bakın

İlk iş, span’larınızın sorgu metnini taşıyıp taşımadığını görmek. Grafana Cloud Traces’te birkaç database span’ı açın ve db.query.text veya db.statement attribute’unu arayın. Biri varsa ve Database Observability o sorguyu toplamışsa trace linkage büyük ihtimalle hiçbir kod değişikliği olmadan çalışır.

Attribute yoksa önce o servisin OpenTelemetry instrumentation ayarlarına bakın. Grafana, sorgu metninin kaydedilme biçiminin dile ve kullanılan instrumentation’a göre değiştiğini belirtiyor.

Hâlâ db.statement üreten servisleri hemen taşımanız gerekmiyor. Destek iki attribute adını da kapsıyor, bu yüzden stabil convention’lara geçişi kendi takviminize göre planlayın.

Sqlcommenter’ı hemen açmayın

Grafana önce metin eşleştirmeyi, ardından isteğe bağlı olarak sqlcommenter’ı öneriyor. Bu sıranın iki gerekçesi var. Sqlcommenter her database engine’ini desteklemiyor ve Grafana, database cache’lerini olumsuz etkileyebileceğini belirtiyor.

Cache etkisinin mantığı basit. Her çalıştırmaya farklı bir trace ID yorumu eklenince aynı sorgunun metni her seferinde değişiyor. Tam sorgu metnini anahtar olarak kullanan bir cache katmanı bu durumda aynı sorguyu her seferinde yeni bir sorgu gibi görebilir.

Sqlcommenter’ı yaygınlaştırmadan önce şu sırayı izleyin:

• Stack’inizde sorgu metnine göre cache tutan bir katman olup olmadığını belirleyin.
• Kullandığınız engine’in sqlcommenter desteğini doğrulayın.
• Yavaşlık şikâyetinin en çok geldiği tek bir servisle başlayın.
• Açmadan önceki ve sonraki cache davranışını karşılaştırın, sonra karar verin.

Peki belirli bir çalıştırmayı görmek size ne kazandırıyor? Sorunlarınız çoğunlukla plan değişikliği veya genel yavaşlıksa, sorgunun örnekleri ve geçmiş performansı zaten yeterli olur. Tek tek çalıştırmalar arasındaki farkı, örneğin lock beklemesini, kovalıyorsanız sqlcommenter’ın getirdiği kesinlik daha anlamlı.

Sorgu metni trace backend’ine gidiyor

Grafana’nın teknik ayrıntılar arasında değindiği bir nokta güvenliği ilgilendiriyor. Instrumentation’a göre literal değerler maskelenebiliyor veya olduğu gibi kalabiliyor. Literal’ler korunuyorsa e-posta adresi, kullanıcı ID’si veya token gibi değerler span attribute’u olarak trace reposuna yazılıyor.

Trace linkage için sorgu metnini span’lara eklemeden önce birkaç örnek span’da literal’lerin maskelenip maskelenmediğini kontrol edin. Grafana, eşleştirmenin maskeli ve maskesiz biçimleri, farklı parametre placeholder’larını ve engine’in kendi normalizasyonunu kapsadığını söylüyor. Maskelemeyi açık tutmak bu nedenle metin eşleştirmeyi bozmamalı ve trace saklama alanınıza hassas veri yazılmasını önler.