İyi log yazmak: Gece 3'te sorunu bulmanızı sağlayacak 8 alışkanlık

Canlı ortamdaki bir sorunu çözerken elinizdeki tek kanıt çoğu zaman loglardır. Hata ayıklayıcı yoktur, sorunu tekrar üretemezsiniz ve kullanıcı yalnızca "çalışmıyor" der. Loglar iyi yazılmışsa sorun dakikalar içinde bulunur. Kötü yazılmışsa saatlerce karanlıkta el yordamıyla ilerlersiniz.

1. Seviyeleri doğru kullanın

Çoğu log kütüphanesi benzer seviyeler sunar. Her birinin bir anlamı vardır:

• DEBUG: Geliştirme sırasında işe yarayan ayrıntılar. Canlı ortamda genellikle kapalıdır.
• INFO: Normal ama kayda değer olaylar: "Sipariş oluşturuldu", "Kullanıcı giriş yaptı", "Gece yedeği tamamlandı."
• WARNING: Beklenmedik ama sistemin idare edebildiği durumlar: "Ödeme servisi yavaş yanıt verdi, ikinci denemede başarılı oldu."
• ERROR: Bir işlemin başarısız olduğu durumlar: "Sipariş kaydedilemedi."
• CRITICAL: Sistemin çalışmaya devam edemediği durumlar: "Veritabanına bağlanılamıyor."

Her şeyi ERROR olarak loglamak, gerçek hataların gürültüde kaybolmasına yol açar. Her şeyi INFO olarak loglamak da uyarı sistemi kurmayı imkânsız kılar.

2. Bağlam ekleyin

Kötü bir log satırı:

ERROR: Ödeme başarısız

İyi bir log satırı:

ERROR: Ödeme başarısız siparis_id=48213 kullanici_id=1902 tutar_kurus=45900 saglayici=iyzico hata_kodu=10051 sure_ms=2840

İkinci satırı okuyan kişi hangi siparişin, hangi kullanıcının, hangi sağlayıcıda, hangi hatayla ve ne kadar sürede başarısız olduğunu hemen bilir. Kendinize şu soruyu sorun: "Bu satırı gece 3'te, kodun karşımda olmadığı bir anda okusam ne anlarım?"

3. Yapılandırılmış log kullanın

Metin içine gömülmüş değerleri sonradan ayıklamak zordur. Logları JSON gibi yapılandırılmış bir biçimde yazmak, onları aranabilir ve filtrelenebilir hâle getirir:

{"zaman":"2026-09-23T18:30:12Z","seviye":"error","mesaj":"Ödeme başarısız","siparis_id":48213,"saglayici":"iyzico","hata_kodu":"10051","istek_id":"a91f3c"}

Bu biçimde "son bir saatte iyzico'dan gelen bütün 10051 hatalarını göster" gibi bir sorgu tek satırla yapılabilir. PHP'de Monolog, Node.js'te pino, Python'da structlog bu işi kolaylaştırır.

4. Her isteğe bir kimlik verin

Bir isteğin yolculuğu birden fazla servise ve onlarca log satırına yayılabilir. İsteğin başında rastgele bir istek kimliği (request id, correlation id) üretin ve o isteğe ait her log satırına ekleyin. Kullanıcıya gösterdiğiniz hata sayfasında da bu kimliği gösterin:

Bir sorun oluştu. Destek ekibine iletirken şu kodu belirtin: a91f3c

Kullanıcı bu kodu ilettiğinde, ilgili bütün satırları tek bir aramayla bulursunuz.

5. Asla loglamayın

Loglar genellikle uygulamanın kendisinden çok daha geniş bir kitleye açıktır: destek ekibi, log servisleri, yedekler. Şunlar loglara asla girmemelidir:

• Şifreler (giriş formundaki şifre dahil; "başarısız giriş" logunda bile)
• Oturum çerezleri, API anahtarları, erişim belirteçleri (token)
• Kredi kartı numaraları ve CVV
• T.C. kimlik numarası gibi hassas kişisel veriler ve sağlık bilgileri

İstek gövdesini ya da başlıklarını olduğu gibi loglayan kod, bu kuralları farkında olmadan çiğner. Hassas alanları maskeleyen bir filtre kullanın.

6. İstisnaları eksiksiz loglayın

try {
    $odeme->tahsilEt($siparis);
} catch (Throwable $e) {
    $log->error('Ödeme başarısız', [
        'siparis_id' => $siparis->id,
        'istisna'    => $e,      // Monolog mesajı, dosyayı, satırı ve yığın izini yazar
    ]);
    throw $e;
}

Yalnızca $e->getMessage() yazmak, hatanın nerede oluştuğu bilgisini kaybettirir. Bir de şuna dikkat edin: Aynı istisnayı her katmanda yakalayıp loglarsanız, tek bir hata loglarda beş farklı satır olarak görünür. Ya loglayıp hatayı orada çözün ya da loglamadan yukarı iletin.

7. Sessizce yutmayın

try { ... } catch (Exception $e) { }   // en tehlikeli satır

Boş bir catch bloğu, bir hatanın hem kullanıcıdan hem de sizden gizlenmesidir. Hatayı gerçekten görmezden gelmek istiyorsanız bile en azından bir WARNING satırı yazın ve nedenini bir yorum satırında açıklayın.

8. Logları yönetin

• Döndürün: logrotate ya da log kütüphanesinin kendi döndürme özelliğiyle dosyaların sonsuza kadar büyümesini engelleyin.
• Saklama süresi belirleyin: Kişisel veri içeren logları gereğinden uzun tutmak, KVKK açısından da risklidir.
• Merkezileştirin: Birden fazla sunucunuz varsa, logları tek bir yerde toplayan bir sistem (Loki, Elasticsearch, Graylog ya da yönetilen bir servis) her sunucuya tek tek bağlanmaktan çok daha verimlidir.
• Uyarı kurun: Loglar kimse bakmadığında işe yaramaz. ERROR sayısı belirli bir eşiği geçtiğinde bildirim alın.

İyi log yazmak fazladan zaman almaz; yalnızca alışkanlık ister. O alışkanlığın karşılığını da ilk ciddi olayda fazlasıyla alırsınız.