Yapılandırılmış Günlükleme: Aranabilir Kayıtlar Üretmek
Bir müşteri "sipariş veremedim" diyor. Günlük dosyalarında arama yapıyorsunuz ama elinizde yalnızca serbest metin satırları var. Hangi kullanıcı, hangi istek, hangi sipariş — hiçbiri güvenilir biçimde filtrelenemiyor. Sorun kayıt tutmamak değil, kayıtların biçimi.
Bu yazı, makine tarafından okunabilir günlük üretmeyi ele alıyor.
İki Kayıt Biçimi
| Serbest metin | Yapılandırılmış |
|---|---|
| İnsan okur | Makine de okur |
| Desenle aranır | Alanla filtrelenir |
| Biçim değişince arama bozulur | Alan eklemek zarar vermez |
Üçüncü satır uzun vadeli farkı gösterir: serbest metin kayıtlarında mesajın yazımını değiştirmek, o mesaja dayanan tüm arama ve uyarı kurallarını sessizce bozar — yapılandırılmış kayıtta alan adı sabit kaldığı sürece hiçbir şey bozulmaz.
Bu bozulma fark edilmez çünkü hata üretmez.
Uyarı yalnızca artık hiç tetiklenmez.
İkinci satır ise günlük arama hızını belirler.
Her Kayıtta Bulunması Gerekenler
- Zaman damgası.
- Önem düzeyi.
- Olay adı.
- İstek kimliği.
Dördüncü madde en değerlisidir: her isteğe benzersiz bir kimlik verip tüm kayıtlara eklemek, bir kullanıcının tek bir tıklamasının sistemde ürettiği bütün satırları tek filtreyle toplamanızı sağlar.
Bu kimlik hata sayfasında da gösterilebilir.
Müşteri numarayı ilettiğinde olayın tamamı anında bulunur.
Üçüncü madde ise sabit bir olay adı kullanmayı gerektirir.
Değişkeni Mesaja Gömmemek
- Mesaj sabit kalmalı.
- Değişkenler ayrı alanda olmalı.
- Gruplama böyle mümkün olur.
Üçüncü madde analiz gücünü belirler: kullanıcı numarasını mesaj metninin içine yazarsanız her satır benzersiz olur ve aynı hatanın kaç kez tekrarlandığını sayamazsınız — numarayı ayrı bir alana koymak, gruplamayı ve saymayı mümkün kılar.
Bu ayrım, en sık görülen hataları listelemenizi sağlar.
Aksi hâlde her satır tek başına durur.
Eğilim analizi yapılamaz.
Önem Düzeyleri
| Düzey | Kullanım |
|---|---|
| Hata ayıklama | Geliştirmede açık |
| Bilgi | Önemli iş olayları |
| Uyarı | Beklenen ama istenmeyen |
| Hata | Müdahale gerektiren |
Dördüncü satır disiplin gerektirir: hata düzeyi yalnızca birinin bakması gereken durumlar için kullanılmalıdır — her başarısız kullanıcı girişini hata olarak kaydetmek, gerçek hataların gürültü içinde kaybolmasına yol açar.
Kullanıcı hataları bilgi veya uyarı düzeyindedir.
Bu ayrım, uyarı sistemini kullanılabilir tutar.
Düzey enflasyonu, izlemeyi işlevsiz kılar.
Kayda Girmemesi Gerekenler
- Şifre ve anahtarlar.
- Kart bilgileri.
- Oturum belirteçleri.
- Tam kişisel veriler.
Üçüncü madde çok sık atlanır: hata ayıklama sırasında tüm istek başlıklarını kaydetmek, oturum belirteçlerinin günlüklere düşmesi demektir — o günlüğe erişen biri hesapları ele geçirebilir.
Günlükler genellikle uygulamadan daha az korunur.
Hassas alanlar kayıt anında maskelenmelidir.
Bu maskeleme kütüphane düzeyinde yapılmalıdır.
Bağlam Eklemek
- Kullanıcı kimliği.
- Sunucu adı.
- Sürüm numarası.
Üçüncü madde dağıtım sonrası teşhisi kolaylaştırır: her kayda uygulama sürümünü eklemek, bir hatanın hangi sürümle başladığını tek sorguyla göstermeye yeter — geri alma kararı böyle dakikalar içinde verilir.
İkinci madde çok sunuculu ortamlarda zorunludur.
Sorunun tek sunucuda mı olduğu anında görülür.
Bu alanlar otomatik eklenmelidir.
Hacim Yönetimi
| Sorun | Çözüm |
|---|---|
| Disk doluyor | Döndürme ve saklama süresi |
| Çok fazla kayıt | Düzey ayarı |
| Tekrarlayan hata seli | Örnekleme |
Üçüncü satır kritik anlarda hayat kurtarır: bir dış servis çöktüğünde saniyede binlerce aynı hata kaydı üretilir ve bu sel diski dakikalar içinde doldurabilir — aynı hatanın yalnızca bir kısmını kaydetmek hem diski hem okunabilirliği korur.
Sayaç, kaç kez tekrarlandığını yine de gösterir.
Birinci satır ise temel bir zorunluluktur.
Disk dolduğunda uygulama da durur.
İnsan Okunabilirliği
- Üretimde makine biçimi.
- Geliştirmede okunaklı biçim.
- Aynı kod, farklı çıktı.
Üçüncü madde iki ihtiyacı birden karşılar: günlük kütüphanesinin çıktı biçimini ortama göre değiştirmek, geliştiricinin terminalde okunaklı satırlar görmesini sağlarken üretimde makine tarafından işlenebilir kayıtlar üretir.
Kod tarafında hiçbir değişiklik gerekmez.
Yalnızca yapılandırma farklıdır.
Bu, yapılandırılmış günlüklemeye geçişin önündeki en büyük itirazı kaldırır.
Günlük hacmini ve saklama süresini kendiniz belirleyebilmek için disk ve yapılandırma denetimi gerekir; sanal sunucu barındırma paketleri ile günlük altyapınızı ihtiyacınıza göre ölçekleyebilirsiniz.
Sonuç
Günlük tutmak yetmez; aranabilir tutmak gerekir. Değişkenleri mesaj metnine gömmek her satırı benzersiz kılar ve aynı hatanın kaç kez tekrarlandığını sayamazsınız. Her isteğe benzersiz kimlik verin, sürüm ve sunucu adını otomatik ekleyin, hassas alanları maskeleyin ve hata düzeyini disiplinli kullanın — her başarısız girişi hata saymak, gerçek hataları gürültüde kaybeder.
Sıkça Sorulan Sorular (SSS)
Yapılandırılmış günlüğe neden geçmeliyim?
Serbest metinde mesajın yazımını değiştirmek, o mesaja dayanan tüm arama ve uyarı kurallarını sessizce bozar; hata üretmediği için fark edilmez, uyarı yalnızca artık tetiklenmez. Yapılandırılmış kayıtta alan adı sabit kaldığı sürece hiçbir şey bozulmaz.
İstek kimliği ne işe yarar?
Her isteğe benzersiz kimlik verip tüm kayıtlara eklemek, bir kullanıcının tek tıklamasının ürettiği bütün satırları tek filtreyle toplamanızı sağlar. Bu kimliği hata sayfasında da gösterirseniz müşteri numarayı ilettiğinde olayın tamamı anında bulunur.
Günlüğe neyi yazmamalıyım?
Şifreleri, anahtarları, kart bilgilerini ve oturum belirteçlerini. Hata ayıklarken tüm istek başlıklarını kaydetmek belirteçlerin günlüğe düşmesi demektir ve o günlüğe erişen biri hesapları ele geçirebilir. Maskelemeyi kütüphane düzeyinde yapın.
Hata seli diski dolduruyor?
Örnekleme kullanın. Bir dış servis çöktüğünde saniyede binlerce aynı kayıt üretilir; aynı hatanın yalnızca bir kısmını kaydetmek hem diski hem okunabilirliği korur ve sayaç kaç kez tekrarlandığını yine gösterir.
