Günlük Kaydını Doğru Yapmak: Gözlemlenebilirlik Vakfı

Bu kılavuz, hizmetlerinizi daha etkili bir şekilde izleyebilmenizi ve sorunları giderebilmenizi sağlamak için sizi temel bilgiler ve uygulamalarla donatmayı amaçlamaktadır.

Uygulama geliştirmede, günlüğe kaydetme genellikle göz ardı edilir, ancak bu, sağlam ve gözlemlenebilir bir sistem oluşturmanın çok önemli bir bileşenidir. Doğru günlük kaydı uygulamaları, uygulamanızın görünürlüğünü artırabilir, iç işleyişine ilişkin anlayışınızı derinleştirebilir ve genel uygulama sağlığını iyileştirebilir.

Varsayılan Günlük Kaydı

Uygulamanızın giriş noktalarına varsayılan günlük kaydı mekanizmalarını dahil etmek son derece faydalıdır. Bu otomatik günlük kaydı, önemli etkileşimleri yakalayabilir ve potansiyel olarak giriş noktasının argümanlarını içerebilir. Ancak şifreler gibi hassas bilgilerin günlüğe kaydedilmesi gizlilik ve güvenlik riskleri oluşturabileceğinden dikkatli olmak çok önemlidir.

Ortak Giriş Noktaları

• API Uç Noktaları : Gelen istekler ve yanıtlarla ilgili ayrıntıları günlüğe kaydedin
• Arka Plan İşleri : İşin başlangıç noktalarını, yürütme ayrıntılarını ve sonuçlarını günlüğe kaydedin
• Eşzamansız Olaylar : Eşzamansız olayların ve ilgili etkileşimlerin işlenmesini günlüğe kaydedin

Kapsamlı Günlük Kaydı

Uygulamanızın gerçekleştirdiği her önemli eylem, özellikle de durumunu değiştiren eylemler, bir günlük girişi oluşturmalıdır. Bu kapsamlı günlük kaydı yaklaşımı, ortaya çıktıklarında sorunları hızlı bir şekilde tanımlamanın ve ele almanın anahtarıdır ve uygulamanızın sağlığı ve işlevselliğine ilişkin şeffaf bir görünüm sunar. Günlük kaydındaki bu titizlik, daha kolay teşhis ve bakım sağlar.

Uygun Günlük Düzeyini Seçme

Uygulamanız tarafından oluşturulan büyük miktarda veriyi yönetmek ve yorumlamak için uygun günlük seviyelerini benimsemek çok önemlidir. Günlükleri önem derecesine ve alaka düzeyine göre kategorilere ayırarak, kritik sorunların hızlı bir şekilde tanımlanmasını ve ele alınmasını sağlarken, daha az acil olan bilgilerin, izleme çabalarınızı yormadan erişilebilir kalmasını sağlarsınız.

Aşağıda günlük seviyelerini etkili bir şekilde kullanmaya yönelik bir kılavuz bulunmaktadır:

Hangi Kimliklerin Kaydedileceği - Hiyerarşik Yaklaşım

Uygulamanızdaki eylemleri günlüğe kaydederken, doğrudan ilgili varlıkların kimlikleri de dahil olmak üzere, günlük bilgilerinin veritabanı verilerine bağlanması açısından çok önemlidir. Hiyerarşik bir yaklaşım, öğeleri üst gruplarına veya kategorilerine bağlayarak uygulamanızın belirli bir bölümüne bağlı tüm günlükleri hızlı bir şekilde bulmanıza yardımcı olur.

Örneğin, bir mesaj gönderilemediğinde yalnızca sohbetin kimliğini kaydetmek yerine, sohbet odasının ve ait olduğu şirketin kimliklerini de kaydetmelisiniz. Bu şekilde daha fazla bağlam kazanırsınız ve sorunun daha geniş etkisini görebilirsiniz.

Örnek Günlük Girişi:

Failed to send the message - chat=$roomId, chatRoomId=chatRoomId, company=$companyId

Üretim Günlükleri Örneği

Aşağıda hiyerarşik yaklaşım kullanıldığında üretim günlüklerinin nasıl görünebileceğine dair bir örnek verilmiştir:

Tutarlılık ve Standardizasyon

Standart Önekler

Günlük formatlarını tüm ekiplerde standartlaştırmak, günlüklerinizin okunmasını ve anlaşılmasını çok daha kolay hale getirebilir. Göz önünde bulundurulması gereken bazı standartlaştırılmış önekler şunlardır:

• Bir şeyler yapmaya başlamak
• Bir şey yapılamadı
• Bir şeyi yapmayı tamamladım
• Bir şeyi yapmayı atladım
• Bir şeyi yapmayı yeniden dene

Değişken Değerlerini Ayrı Ayrı Günlüğe Kaydedin

Değişken adlarını ve değerlerini günlük iletilerinin gövdesinden ayırmak çeşitli avantajlar sunar:

• Günlük Aramayı ve Ayrıştırmayı Basitleştirir: Belirli bilgileri filtrelemeyi ve bulmayı kolaylaştırır
• Günlük Mesajı Oluşturmayı Kolaylaştırır: Günlük mesajları yazma sürecini basitleştirir
• Mesaj Dağınıklığını Önler: Büyük değerler günlük mesajının okunabilirliğini bozmaz

Örnek Günlük Formatı:

 Log message - valueName=value

Önerilen Uygulamaları Kullanan Günlük Örnekleri

Teorik Örnek

Tartışılan en iyi uygulamaları takip eden iyi yapılandırılmış günlük girişlerinin örnekleri aşağıda verilmiştir:

 2023-10-05 14:32:01 [INFO] Successful login attempt - userId=24543, teamId=1321312 2023-10-05 14:33:17 [WARN] Failed login attempt - userId=536435, teamId=1321312

Bu örnekler şunları göstermektedir:

• Standartlaştırılmış Günlük Ön Ekleri : "Başarılı giriş denemesi" ve "Başarısız giriş denemesi" gibi net, tutarlı ön ekler, günlüklerin anlaşılmasını kolaylaştırır.

• Ayrılmış Değişken Değerleri : Değişken adları ve değerleri günlük mesajından ayrılarak netlik korunur ve aramalar basitleştirilir.

• Okunabilirlik ve Tutarlılık : Yapılandırılmış format, günlüklerin okunmasının ve ayrıştırılmasının kolay olmasını sağlayarak etkili sorun giderme ve izlemeye yardımcı olur.

Üretim Günlükleri Örneği

Önerilen uygulamaları kullanırken üretim günlüklerinin nasıl görünebileceğine dair bir örnek aşağıda verilmiştir:

İzleme kimlikleri

Günlükleri belirli bir kullanıcı eylemiyle etkili bir şekilde ilişkilendirmek için günlüklerinize bir traceId veya correlationId olarak da adlandırılan bir öğe eklemek çok önemlidir. Kimlik, söz konusu giriş noktası tarafından tetiklenen mantık tarafından oluşturulan tüm günlüklerde tutarlı kalmalı ve olayların sırasına ilişkin net bir görünüm sunmalıdır.

Uygulama Örneği

Datadog gibi bazı izleme hizmetleri günlükleri kutudan çıkar çıkmaz gruplandırmayı sağlarken, bu aynı zamanda manuel olarak da uygulanabilir. Spring kullanan bir Kotlin uygulamasında, HandlerInterceptor kullanarak REST istekleri için bir izleme kimliği uygulayabilirsiniz.

 @Component class TraceIdInterceptor : HandlerInterceptor { companion object { private const val TRACE_ID = "traceId" } override fun preHandle(request: HttpServletRequest, response: HttpServletResponse, handler: Any): Boolean { val traceId = UUID.randomUUID().toString() MDC.put(TRACE_ID, traceId) return true } override fun afterCompletion(request: HttpServletRequest, response: HttpServletResponse, handler: Any, ex: Exception?) { MDC.remove(TRACE_ID) } }

Bu önleyici, her istek için benzersiz bir traceId oluşturur, bunu isteğin başlangıcında MDC'ye ekler ve istek tamamlandıktan sonra kaldırır.

traceId İçeren Örnek Günlükler

Bu tür günlük toplama işleminin uygulanması, aşağıdaki örneğe benzer şekilde günlükleri filtrelemenize olanak tanır

Günlüklerde UUID ve Uzun Kimlikleri Kullanma

Birçok sistemde varlıklar birincil tanımlayıcıları olarak UUID veya Long Kimlikleri kullanabilirken, bazı sistemler farklı amaçlar için her iki kimlik türünü de kullanabilir. Her türün günlüğe kaydetme amaçları açısından etkilerini anlamak, bilinçli bir seçim yapmak için çok önemlidir.

İşte dikkate alınması gereken hususların bir dökümü:

Okunabilirlik: Long kimliklerin okunması daha kolaydır ve özellikle Long aralığın üst ucunda değillerse önemli ölçüde daha kısadır.

Benzersiz Değer: UUID kimlikleri sistem genelinde benzersizlik sağlayarak, kimlik çakışması sorunlarıyla karşılaşmadan bir kimlik kullanarak günlükleri aramanıza olanak tanır. Buradaki çarpışmalar, ilgisiz veritabanı tablolarındaki 2 varlığın aynı Long Kimliğe sahip olma ihtimalinin olduğu anlamına gelir.

Sistem Sınırlamaları : Uzun birincil anahtarları varlık kimlikleri olarak kullanan sistemlerde, rastgele bir UUID kimliği eklemek genellikle basittir; UUID varlık kimliklerine sahip dağıtılmış bir sistemde, özellikle günlüğe kaydetme için Long kimliklere sahip olmak zorlayıcı veya maliyetli olabilir.

Mevcut Günlükler: Günlüklerde kullanılan kimlik türlerindeki tutarlılık, en azından varlık başına kritik öneme sahiptir. Sistem zaten bazı varlıklar için günlükler üretiyorsa ve bunların hepsini değiştirmeyi düşünmüyorsanız, varlığı tanımlamak için halihazırda kullanılan türe bağlı kalmak daha iyidir. Geçiş döneminde her iki kimliğin de günlüğe kaydedilmesi düşünülebilir, ancak kalıcı olarak birden fazla kimliğe sahip olmak, günlükleri gereksiz yere karmaşık hale getirecektir.

Çözüm

Etkili hizmet gözlemlenebilirliği için uygun kayıt uygulamaları önemlidir. Kapsamlı günlük kaydı, uygun günlük düzeyleri, izleme kimlikleri ve standartlaştırılmış günlük formatlarını birleştirerek uygulamalarınızı izleme ve sorun giderme yeteneğinizi önemli ölçüde artırabilirsiniz. Bu uygulamalar, günlüklerinizin netliğini ve tutarlılığını geliştirerek sorunları hızlı bir şekilde teşhis edip çözmenizi kolaylaştırır.

Bu yazıyı okumaya zaman ayırdığınız için teşekkür ederiz!