Keycloak, OpenTelemetry için Java agent yerine native Quarkus seçti

OpenTelemetry Developer Experience SIG’in vaka serisindeki yeni yazı, Keycloak OpenTelemetry entegrasyonunun maintainer’lar gözünden nasıl kurulduğunu anlatıyor. Keycloak ekibi, OpenTelemetry Java agent’ının başlangıç süresine onlarca saniye eklediğini ölçünce native Quarkus entegrasyonuna geçti. Tracing artık Keycloak’un kendi yapılandırmasıyla, CLI üzerinden ya da Kubernetes Operator ile açılabiliyor.

Keycloak nedir, ne işe yarar?

Keycloak, açık kaynak bir kimlik ve erişim yönetimi (IAM) sunucusudur. Uygulamalara OpenID Connect, OAuth 2.0 ve SAML üzerinden tek oturum açma ve authentication ekler. Kullanıcı federasyonu, LDAP entegrasyonu ve rol tabanlı yetkilendirme destekler. Kurumlar onu kendi altyapısında çalıştırır; ticari alternatifleri arasında Okta ve Auth0 sayılabilir.

OpenTelemetry nedir, ne işe yarar?

OpenTelemetry, trace, metrik ve log verisini üretip dışa aktarmak için kullanılan açık kaynak bir standart ve araç setidir. CNCF bünyesindeki proje; dil bazlı SDK’lar, otomatik enstrümantasyon agent’ları ve OTLP protokolüyle veri toplayan Collector bileşeninden oluşur. Toplanan veri Jaeger, Prometheus ya da ticari observability platformlarına gönderilebilir.

Keycloak OpenTelemetry desteği kimi ilgilendiriyor?

Bu yazı iki ayrı okura dokunuyor. Birincisi Keycloak işleten platform ekipleri: tracing artık ek bir agent ya da ayrı extension olmadan, Keycloak’un kendi yapılandırmasından açılıyor. İkincisi kendi yazılımına telemetri gömmek isteyen maintainer’lar. Keycloak ekibinin kararları, observability (gözlemlenebilirlik) tasarımında hangi bedellerin ödendiğini açıkça gösteriyor.

Kaynaktaki yaklaşımın iskeleti şöyle:

• Java agent ile keşif, ölçülen başlangıç maliyeti yüzünden native Quarkus entegrasyonuna geçiş
• Önce metrik, sonra tracing; ikisini exemplar’larla bağlama
• Tüm sinyalleri tek bir native yapılandırma altında toplama
• Push tabanlı telemetriyi tehdit modelinin parçası sayma

Keycloak’u HPA ile ölçekleyen ya da sık restart eden ekipler için başlangıç süresi doğrudan erişilebilirlik demek. Agent yüzünden onlarca saniye uzayan açılış, yük artışında yeni pod’ların geç devreye girmesi anlamına geliyor. Keycloak’u bugün Java agent ile izliyorsanız native tracing’e geçişi planlayın.

Tracing’i açarken localhost tuzağı

Keycloak OpenTelemetry desteği varsayılan olarak açık geliyor, ama tek başına veri göndermiyor. En az bir bileşeni, örneğin tracing’i etkinleştirmeniz gerekiyor:

bin/kc.sh start --tracing-enabled=true

Operator ile kurulumda Keycloak resource’unda telemetry altında endpoint, serviceName ve protocol alanları var. Varsayılan endpoint http://localhost:4317, protokol gRPC. Burada dikkat: Kubernetes’te localhost, pod’un kendi ağ namespace’ini gösteriyor. Pod içinde bir collector sidecar (yardımcı container) çalışmıyorsa span’ler hiçbir yere ulaşmaz.

Operator’ü varsayılanlarla kurup yalnızca tracing’i açtıysanız endpoint’i cluster’daki collector servisinizin adresine çevirin. CR şeması v2alpha1 sürümünde, yani alanlar ileride değişebilir. Tam yapı için Keycloak’un telemetry ve tracing dokümantasyonuna bakın.

Exemplar ile p99 gecikmesine inmek

Keycloak’ta yavaşlığın kaynağı çoğu zaman uygulamanın dışında: veritabanı ya da LDAP. Metrik size login süresinin arttığını söyler, nedenini söylemez. Trace ise isteğin hangi adımda beklediğini gösteriyor.

Exemplar bu ikisini birleştiriyor. 99. yüzdelik gecikme grafiğindeki bir sıçramadan doğrudan temsilci bir trace’e geçebiliyorsunuz. Bunun çalışması için metrik backend’inizin ve dashboard aracınızın exemplar’ları saklayıp göstermesi gerekiyor. Tracing’i açmadan önce bu desteği kontrol edin; yoksa iki sinyal yine ayrı ekranlarda kalır.

Push modeli tehdit modelinizi değiştiriyor

Prometheus’ta scraper bilinen bir endpoint’e kendisi bağlanıyor. Verinin nereden geldiği belli, yük de scraper’ın temposuyla sınırlı. OTLP ile push modelinde yön tersine dönüyor: collector, kendisine bağlanan herkesten veri kabul ediyor.

Ekibin sorusu yerinde. Ele geçirilmiş bir pod, collector’ı sahte sinyallerle boğabilir mi? Push modelinde yerleşik backpressure yok. Keycloak gibi bir IAM servisinde observability yığınının kendisi bir arıza noktasına dönüşmemeli.

Pratik karşılığı:

• Collector’ın 4317 portunu yalnızca beklenen namespace’lere açan bir NetworkPolicy yazın.
• Collector tarafında bellek sınırı ve rate limiting (hız sınırlama) tanımlayın.
• Collector yavaşladığında ya da çöktüğünde authentication akışının nasıl davrandığını yük altında ölçün.

Semantic convention boşluğu ve Weaver

Identity provider’lar için standart semantic convention henüz yok. Keycloak bu yüzden kendi önekleriyle attribute üretiyor. Bedeli sonra ödenecek: upstream convention geldiğinde attribute adları değişecek, bu adlara bağlı dashboard ve alarmlar kırılacak.

Keycloak trace’leri üzerine sorgu ya da alarm kuruyorsanız attribute adlarını tek bir yerde toplayın, örneğin collector’daki dönüşüm kurallarında ya da dashboard değişkenlerinde. Ad değiştiğinde onlarca paneli elle düzeltmek zorunda kalmazsınız.

Keycloak OpenTelemetry deneyiminden maintainer’lara çıkan ders daha net. Agent’ın maliyetini benimsemeden önce ölçün; Keycloak örneğinde kayıp onlarca saniyeydi ve agent maintainer’ları bu yükün yaklaşımın doğasında olduğunu doğruluyor. Attribute adlarını bilinçli seçin, upstream convention geldiğinde geçişe hazır olun. Ekip, breaking change’leri deployment öncesi yakalamak için Weaver gibi otomatik doğrulama araçlarını öneriyor; telemetri şemanızı CI pipeline’ına bu noktada bağlayabilirsiniz.