Klasik log satırı bir hikâyedir: tarih, seviye, sonra insan gözüne göre dizilmiş bir cümle. İnsan okurken sorun yok; ama üç yüz bin satırın içinde "bu hata hangi kiracıda, hangi istekten doğdu" diye sorduğunuzda cümle düşmanınıza dönüşür. Yapısal loglamanın iddiası budur: kaydı yazarken insan için değil, önce makine için yapılandırın; okunabilirlik biçimleyiciden gelsin.

Grep'in sınırı, sorgunun özgürlüğü

Serbest metinde alan yoktur, varsayım vardır. grep "ödeme" size ödemeyle ilgili her satırı verir — komutun kendisini de, örnek cümleyi de. Yapısal kayıtta ise her satır alan-değer çiftidir; "seviyesi error olan, sipariş servisinin, geçen saatteki kayıtları" tek satır sorgudur. Daha da önemlisi alanlar sayılabilir olur: hangi kiracı en çok hata üretti, p95 gecikme hangi uç noktada birikiyor — bunlar grep ile değil, toplama sorguları ile cevaplanır.

{"ts":"2026-06-22T09:14:02Z","level":"error","service":"order","trace_id":"7f3a","tenant":"ataturkopark","msg":"stok servisi zaman aşımı","timeout_ms":5000}

Ne yazmalı, ne yazmamalı

Yapısal loglamanın ilk disiplini şemadır: zaman, seviye, servis adı, iz kimliği ve mesaj her kayıtta aynı alan adında durmalı. İkinci disiplin, bağlamı mesaja değil alanlara koymaktır — kullanıcı 42 siparişi geçemedi yerine user_id: 42, err: "payment_declined". Üçüncüsü, gizli veriyi kayda sokmamaktır: şifre, kart numarası, tam kişisel bilgi. Log bir veritabanı değildir ama yıllarca saklanır; ne yazdığınızı bilmeden yazmayın.

# Aynı dosyada iki dünyanın birlikteliği: yapısal kayıt, okunur çıktı
cat app.jsonl | jq -c 'select(.level=="error" and .service=="order") | {ts,trace_id,msg}'

Tutarlılık aracın işi

Geliştiricinin elle JSON yazması sürdürülebilir değildir; yapıyı kütüphaneye yaptırın. Node tarafında pino, Go tarafında zap ve slog bu işin standartlarıdır. Uygulama çıktısını tek satırlık JSON'a sabitledikten sonra ortamdan seviyeyi yönetmek, iz kimliğini HTTP ortasından otomatik geçirmek küçük işlerdir ama tutarlılığı kalıcı yapar. Serbest metin yalnızca insan eliyle yazılan yerlerde kalmalı — istisna izlerinde bile mesaj alanına tek satır, detayı alanlara.

Geçiş bir hafta sonu işi: kütüphaneyi takın, şemayı yazın, mevcut toplama sorgularınızı eski hatlarıyla yan yana çalıştırıp doğrulayın. Sonraki olay gecesi, grep'in on satırlık bilmecesini tek satır sorgunun cevapladığında farka inanacaksınız.

Son bir uyarı: yapısal loglama, log toplama altyapısını değiştirmek demek değildir. Kayıtları hâlâ dosyaya yazıp toplama ajanıyla gönderebilirsiniz; değişen tek şey kaydın biçimidir. Bu yüzden geçişi kademeli yapın — önce tek serviste deneyin, şemayı olgunlaştırın, sorgu alışkanlıklarınızı o şemaya göre güncelleyin, sonra diğer servislere yayın. En çok direnç gösteren ekip üyesi genellikle "grep bana yeter" diyenidir; ona verilecek en iyi cevap, yapısal kayıt üzerinde çalışan grep'tir: jq bilmediğinizde bile, alan adına göre süzülmüş çıktı serbest metinden her zaman temizdir. Aracın adı değişse de alışkanlık korunur; kaybolan yalnızca cümleleri ayrıştırmakla geçen dakikalardır. Bir ay sonra geriye dönüp baktığınızda, eski loglarda aradığınız şeyi bulamamak değil, bulduğunuzu bilmemek üzerine kurulu eski hayatınızı zor tanıyacaksınız. Bu fark, alışkanlıktan kavrama geçişin ta kendisidir.