Yazılımda Hata İzleme ve Loglama Nasıl Kurulur?

Hata izleme ve loglama, canlıdaki yazılımın ne yaptığını ve nerede bozulduğunu müşteri size söylemeden önce görmenizi sağlayan altyapıdır. Kurulumu üç parçadır: her isteği ve önemli işi kayda geçiren yapılandırılmış log, hataları yığın izi ve bağlamıyla toplayan hata takip aracı, ve sistemin sağlığını sayılarla gösteren metrik + alarm. Üçü birlikte kurulmazsa ekip sorunu ancak bir kullanıcı "çalışmıyor" diye yazdığında öğrenir ve neyin, ne zaman, kimde bozulduğunu tahminle bulmaya çalışır.

Log, hata takibi ve metrik: üçü aynı şey değil

Bu üç kavram sık karıştırılır ve biri kurulunca diğerlerinin de kurulduğu sanılır. Oysa her biri farklı bir soruya cevap verir ve birinin eksikliğini diğeri kapatmaz.

• Log: "Ne oldu?" sorusunun cevabı. Her istek, her ödeme denemesi, her arka plan işi zaman damgası ve bağlamıyla tek satır olarak yazılır. Geriye dönük inceleme logdan yapılır.
• Hata takibi: "Ne bozuldu ve kaç kişiyi etkiledi?" sorusunun cevabı. Aynı hatanın bin tekrarı tek kayıtta gruplanır; yığın izi, sürüm numarası ve etkilenen kullanıcı sayısıyla birlikte gelir.
• Metrik: "Sistem şu an sağlıklı mı?" sorusunun cevabı. Yanıt süresi, hata oranı, kuyruk uzunluğu, disk doluluğu gibi sayılar zamana göre izlenir ve alarm bu sayılara bağlanır.

Pratikte en sık görülen tablo şudur: sunucuda düz metin log dosyaları vardır, kimse okumaz, disk dolunca silinir; hata takibi yoktur; metrik olarak yalnızca barındırma panelinin CPU grafiği vardır. Bu düzen sorun olmadığı sürece çalışıyor gibi görünür ve ilk ciddi olayda hiçbir işe yaramaz.

Yapılandırılmış log: aranabilir olmayan log yoktur

Loglamanın ilk kuralı, logun insan için değil sorgu için yazılmasıdır. "Kullanıcı 42 sipariş verdi" gibi serbest metin satırları dosyada güzel görünür ama "dün 14:00-15:00 arasında ödeme adımında hata alan siparişler" sorusuna cevap vermez. Yapılandırılmış logda her satır alanları olan bir kayıttır (genellikle JSON): seviye, mesaj, zaman, istek kimliği, kullanıcı kimliği, işlem adı ve süre ayrı alanlarda durur.

İkinci kural korelasyon kimliğidir. Bir istek API’ye girdiğinde ona tek bir kimlik verilir ve o istek boyunca yazılan her log satırı, çağrılan her iç servis ve kuyruğa atılan her iş bu kimliği taşır. Böylece bir müşteri şikâyetindeki tek istek, beş farklı servisteki kırk satırlık iz olarak tek sorguyla bulunur. Mikroservis mimarisinde bu kimlik olmadan hata ayıklamak neredeyse imkânsızdır; modüler monolitte bile kuyruk ve zamanlanmış işler yüzünden aynı ihtiyaç doğar.

import { randomUUID } from 'node:crypto';
import pino from 'pino';

export const logger = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  redact: ['req.headers.authorization', '*.password', '*.cardNumber', '*.tcKimlik'],
});

// Her isteğe korelasyon kimliği: gelen başlık varsa onu kullan, yoksa üret
export function requestLogger(req, res, next) {
  const requestId = req.headers['x-request-id'] ?? randomUUID();
  req.log = logger.child({ requestId, path: req.path, method: req.method });
  res.setHeader('x-request-id', requestId);

  const started = Date.now();
  res.on('finish', () => {
    req.log.info({ status: res.statusCode, durationMs: Date.now() - started }, 'request completed');
  });
  next();
}

Örnekteki iki ayrıntı önemlidir. Kimlik yanıt başlığına da yazılır; destek ekibi müşteriden bu kimliği alırsa doğrudan ilgili ize gider. Hassas alanlar ise logger seviyesinde maskelenir; geliştiricinin her satırda dikkatli olmasına güvenmek yerine kural tek yerde tutulur.

Loga asla yazılmaması gerekenler

Log dosyası çoğu şirkette veritabanından daha az korunur: daha çok kişi erişir, üçüncü taraf araca gönderilir, yedeklerde yıllarca kalır. Bu yüzden loga yazılan kişisel veri, KVKK uyumu açısından veritabanındaki kadar ciddi bir yükümlülüktür. Parola, kart numarası, oturum ve erişim token’ı, doğrulama kodu, kimlik numarası ve sağlık verisi hiçbir seviyede loga yazılmaz. E-posta ve telefon gerekiyorsa maskelenir; kullanıcı yerine kullanıcı kimliği yazılır. Logların saklama süresi de baştan belirlenir: süresiz tutulan log hem maliyettir hem de hukuki risktir. Bu ilkeler genel çerçevedir, hukuki danışmanlık değildir; kendi saklama sürelerinizi hukuk danışmanınızla netleştirin.

İzleme altyapısının başarı ölçüsü kaç satır log topladığı değil, bir hatayı müşteriden önce fark ettiğiniz olayların oranıdır.

Alarm kuralları: her hata bir alarm değildir

İzleme kurulduktan sonraki en yaygın hata, her hata için bildirim göndermektir. Birinci hafta kanala yüzlerce mesaj düşer, ikinci hafta kanal sessize alınır, üçüncü hafta gerçek kesinti kimsenin görmediği bir mesaj olarak gelir. Alarm tek bir olaya değil, kullanıcıyı etkileyen bir duruma bağlanmalıdır.

• Hata oranı eşiği: son beş dakikada isteklerin belirli bir yüzdesinden fazlası 5xx dönüyorsa alarm; tek bir 500 alarm değildir.
• Yeni hata türü: daha önce görülmemiş bir hata yeni sürümden hemen sonra çıkıyorsa bildirim; bu, CI/CD hattında geri alma kararının girdisidir.
• Kritik iş akışı: ödeme, sipariş ya da giriş adımında başarısızlık sayısı normalin üstüne çıktığında, sayı küçük olsa bile alarm.
• Sessizlik: her gece çalışması gereken yedekleme ya da senkron işi belirli saate kadar "tamamlandı" logu yazmadıysa alarm. Çalışmayan iş hata üretmez, bu yüzden ancak yokluğu izlenerek yakalanır.
• Kaynak: disk doluluğu, veritabanı bağlantı havuzu ve kuyruk uzunluğu dolmadan önce, eğilime göre uyarı.

Sessizlik alarmı özellikle önemlidir: veri yedekleme işinin aylarca çalışmadığı ancak geri yükleme gerektiğinde anlaşılır. Her alarmın bir sahibi ve "bu alarm gelince ne yapılır" diye yazılmış kısa bir adımı olmalıdır; sahibi olmayan alarm gürültüdür.

Hazır araç mı, kendi kurulumunuz mu?

Hata takibi için hazır SaaS araçları ve açık kaynak, kendi sunucunuzda çalışan alternatifleri vardır; log ve metrik için de aynı ikilik geçerlidir. Karar üç soruya bağlıdır: veri nerede durabilir (kişisel veri yurt dışındaki bir araca gidecekse bunun hukuki tarafı ayrıca değerlendirilir), hacim ne kadar (hazır araçlar çoğunlukla olay ya da GB başına ücretlendirir ve hacim büyüdükçe fatura sürpriz yapar), ve sunucuyu kim işletecek (kendi kurulumunuz lisans maliyetini düşürür ama bakımını birinin üstlenmesi gerekir). Küçük ve orta projelerde sık görülen denge, hata takibini hazır araçta, logları ise maliyeti öngörülebilir bir yerde tutmaktır. Uygulamanın kendisi Docker ile paketleniyorsa log’un standart çıktıya yazılması ve toplayıcının bunu konteyner dışından alması en sade kurulumdur.

Yazılım firmasından teslimde istenecekler

İzleme genellikle teklifte yazmaz, projenin sonunda da "sonra ekleriz" denir. Oysa izlemesi olmayan bir sistemi devralan ekip, ilk olayda kör uçar. Teslim listesinde şunlar açıkça bulunmalıdır: logların nereye gittiği ve kaç gün saklandığı, hata takip aracının hesabının sizin şirketinizin adına açılmış olması, tanımlı alarm kuralları ve her birinin alıcısı, korelasyon kimliğinin nasıl bulunacağına dair kısa bir not ve loga yazılmayan alanların listesi. Bu maddeler yazılım geliştirme sözleşmesine kabul kriteri olarak yazılırsa sonradan tartışma çıkmaz.

Sonuç

Hata izleme ve loglama, yazılımın canlıya çıktıktan sonraki hayatını yöneten altyapıdır: yapılandırılmış log ve korelasyon kimliği geçmişi okunur kılar, hata takibi neyin kaç kişide bozulduğunu gösterir, iyi kurulmuş alarm ise sorunu müşteriden önce size söyler. Yeni bir projede izlemeyi ilk sürümün parçası olarak planlamak ya da mevcut sisteminize sonradan kurmak isterseniz özel yazılım hizmetimize göz atabilir veya teklif alabilirsiniz.