Kurumsal uygulamalarda yapılandırılmış JSON loglama: Correlation ID ile dağıtık izleme, log seviyeleri ve merkezi analiz mimarisini detaylarıyla keşfedin.
Hızlı Özet (TL;DR)
Geleneksel düz metin loglar (console.log("Kullanıcı giriş yaptı: " + id)), kurumsal sistemler büyüdükçe ve eşzamanlı işlem hacmi dakikada binlerce isteğe ulaştığında aranması, filtrelenmesi ve anlamlandırılması imkânsız bir metin yığınına dönüşür. Yapılandırılmış loglama (Structured Logging); her log kaydının makine tarafından doğrudan ayrıştırılabilir (machine-parsable), şeması belirli anahtar-değer çiftlerinden oluşan standart bir JSON (JavaScript Object Notation) nesnesi olarak üretilmesidir. Dağıtık mikroservislerde veya çok katmanlı ERP/MES mimarilerinde bir isteğin servisler arasındaki tüm yolculuğunu uçtan uca takip edebilmek için her isteğe benzersiz bir Correlation ID (trace_id) atanmalı, hassas veriler maskelenmeli ve loglar merkezi gözlemlenebilirlik platformlarına (ELK Stack, OpenSearch, Grafana Loki) gerçek zamanlı aktarılmalıdır.
Düz Metin Log vs Yapılandırılmış JSON Log Mimarisi
Bir üretim yönetim yazılımında veya e-ticaret/B2B portalında gece saat 03:15’te belirli bir iş emri kapatılırken oluşan veritabanı kilitlenmesini (deadlock) teşhis etmeye çalıştığınızı düşünün. Düz metin loglarda gigabaytlarca metin dosyası içinde grep veya karmaşık düzenli ifadeler (Regex) ile samanlıkta iğne aramak zorunda kalırsınız. Yapılandırılmış JSON loglamada ise her nitelik indeksli bir sütun gibi sorgulanabilir:
| Kriter | Düz Metin Log (Unstructured Text) | Yapılandırılmış JSON Log (Structured Logging) |
|---|---|---|
| Kayıt Formatı | [2026-09-17 14:00:12] Hata olustu fatura: 104 sure: 820ms | {"timestamp":"2026-09-17T14:00:12.410Z","level":"ERROR","invoiceId":104,"durationMs":820} |
| Arama ve Sorgulama | Yalnızca metin tarama (grep / pahalı Regex) | Alan bazlı milisaniyelik indeks sorgusu (invoiceId == 104 AND durationMs > 500) |
| Performans Metrik Üretimi | Log içinden sayısal ortalama/persentil alınamaz | Loglardan doğrudan P95/P99 yanıt süresi grafikleri ve ısı haritaları üretilir |
| Otomasyon ve Alarm | Metin formatı değiştiğinde alarm kuralları bozulur | Şema sabit olduğu için SIEM, Slack ve PagerDuty alarmlarına %100 uyumludur |
| Dağıtık İzleme (Tracing) | Farklı sunuculardaki loglar arası ilişki kurulamaz | traceId ve correlationId ile 10 farklı mikroservis tek zaman çizelgesinde birleşir |
| Yasal Uyum ve Denetim | KVKK ve 5651 denetimlerinde bütünlük kanıtı zordur | Standart şema, zaman damgası ve maskeleme kurallarıyla denetime tam hazırdır |
Correlation ID (İlişkilendirme Kimliği) ve OpenTelemetry Mimarisi
Modern kurumsal yazılımlarda tek bir kullanıcı aksiyonu arka planda çok sayıda bağımsız bileşeni tetikler. Örneğin bir fabrika operatörü İmalat ERP Çözümleri ekranında “Üretim Paletini Tamamla ve Sevk Et” düğmesine bastığında; istek sırasıyla API Gateway, Kimlik Doğrulama Servisi, Üretim İş Emri Servisi, Depo Stok Düşüm Servisi, Kalite Kontrol Servisi ve e-İrsaliye Entegrasyon Servisi’nden geçer.
İstek Yaşam Döngüsünde Bağlam Taşıma (Context Propagation)
- Sınır Kapısında Kimlik Atama: İstek dış dünyadan veya istemciden Ters Vekil (Reverse Proxy / API Gateway) katmanına ulaştığı ilk milisaniyede, sistem benzersiz bir UUID v4 veya W3C Trace Context (
traceparent) üretir:X-Correlation-ID: 8f9d2a11-4b7c-491e-9c1a-77a2b40e1902. - Senkron ve Asenkron İletim: İlgili servis bir başka iç servise HTTP/gRPC çağrısı yaparken veya RabbitMQ / Apache Kafka kuyruğuna bir olay (event) mesajı bırakırken bu
X-Correlation-IDbaşlığını mesaj üst verisine (header) otomatik ekler. - Log Zenginleştirme (Log Enrichment): Her servis kendi log satırını yazarken geliştiricinin ekstra kod yazmasına gerek kalmadan, çalışma zamanı bağlamından (DiagnosticContext / MDC / AsyncLocalStorage)
correlationId,userId,tenantId,serviceNameveenvironmentalanlarını JSON nesnesine otomatik gömer. - Tek Tıkla Kök Neden Analizi (RCA): Müşteri veya operatör ekranda bir hata kodu gördüğünde, ekranda beliren referans kodunu (Correlation ID) destek ekibine iletir. Sistem mühendisi bu tek kimliği Kibana veya Grafana Loki arama çubuğuna yapıştırarak 6 farklı sunucuda o isteğe ait üretilmiş tüm logları kronolojik sırayla saniyesinde inceler.
Log Seviyeleri (Severity Levels) Nasıl Kurgulanmalı?
Yanlış yapılandırılmış log seviyeleri ya disklerin gereksiz DEBUG çöplüğüyle dolmasına ya da kritik hataların INFO gürültüsü arasında kaybolmasına neden olur:
TRACE ve DEBUG: Geliştirme ve Derin Teşhis Katmanı
Uygulama içindeki döngü adımlarını, SQL sorgularının ham parametrelerini veya üçüncü parti API’lerden dönen ham payload verilerini içerir. Canlı (Production) ortamda varsayılan olarak kapalı tutulmalıdır. Ancak canlı ortamda spesifik bir hatayı yakalamak gerektiğinde, uygulama yeniden başlatılmadan sadece ilgili modül veya belirli bir kullanıcı ID’si için dinamik olarak 10 dakikalığına açılabilmelidir.
INFO: İş Akışı Kilometre Taşları ve Denetim İzleri
Sistemin normal işleyişindeki durum geçişlerini kaydeder. “İş emri #4052 başlatıldı”, “Kullanıcı oturum açtı”, “Gün sonu maliyet hesabı 4.2 saniyede tamamlandı” gibi kayıtlar INFO seviyesindedir. Disk maliyetini ve G/Ç (I/O) yükünü optimize etmek için yüksek frekanslı sağlık kontrolü (/healthz) uç noktaları INFO seviyesinde loglanmamalıdır.
WARN: Kendi Kendini İyileştiren Anomaliler ve Eşik Uyarıları
Sistemin çalışmasını o an durdurmayan ancak yakın gelecekte bir arızaya dönüşebilecek durumları temsil eder. Örneğin; dış e-Fatura servisine yapılan ilk bağlantının zaman aşımına uğrayıp 2. denemede (Retry) başarılı olması, veritabanı bağlantı havuzunun (Connection Pool) %85 doluluğa ulaşması veya bir API yanıt süresinin SLA eşiği olan 1.000 ms’yi aşması WARN olarak kaydedilir.
ERROR ve FATAL: İşlem Başarısızlıkları ve Kritik Çökmeler
Kullanıcı isteğinin veya arka plan görevinin tamamlanamamasına yol açan yakalanmış/yakalanmamış istisnalardır (Exceptions). ERROR logları mutlaka tam yığın izini (stackTrace), hataya sebep olan giriş parametrelerinin güvenli özetini ve correlationId değerini içermelidir. FATAL ise uygulamanın tamamen kapanmasına yol açan (diskin %100 dolması, ana veritabanı kümesinin tamamen erişilemez olması) acil durum seviyesidir ve doğrudan 7/24 nöbetçi mühendisin telefonunu çaldırmalıdır.
KVKK, 5651 ve Siber Güvenlik Açısından Log Maskeleme (PII Redaction)
Yapılandırılmış loglama yapılırken geliştiricilerin en sık düştüğü güvenlik açığı, bir nesneyi olduğu gibi JSON’a serileştirerek (JSON.stringify(requestBody)) log dosyasına basmaktır. Bu hata; kullanıcı parolalarının, JWT erişim belirteçlerinin (Access Token), kredi kartı numaralarının (PAN) veya T.C. Kimlik Numarası gibi kişisel verilerin (PII) düz metin olarak log sunucularına sızmasına yol açar.
Maysa Yazılım’ın geliştirdiği kurumsal mimarilerde, loglama kütüphanesi (Serilog, Pino, Winston, Logback) boru hattına (pipeline) zorunlu bir Veri Maskeleme (Sanitization/Redaction) Katmanı yerleştirilir:
password,token,secret,authorization,cvvanahtarlarına sahip tüm JSON alanları diske veya ağa yazılmadan önce bellekte otomatik olarak[REDACTED]etiketiyle ezilir.- T.C. Kimlik, telefon ve e-posta gibi alanlar KVKK (6698 sayılı Kanun) gereksinimlerine uygun olarak kısmi maskelemeye (
m***@maysabilgisayar.com,532*****89) tabi tutulur. - Log kayıtlarının silinmesini veya değiştirilmesini önlemek adına, Güvenlik Duvarı Firewall ve sunucu logları anlık olarak yalıtılmış bir log sunucusuna (Syslog / WORM depolama) iletilerek TÜBİTAK zaman damgası ile imzalanır.
Yüksek erişilebilirlik, 5651 yasal mevzuat uyumu, Savunma Sanayii İmalat Ağ ve Siber Güvenlik standartları ve gelişmiş log izleme altyapıları için KVKK 5651 Yasal Loglama ve Özel Yazılım Geliştirme sayfalarımızı inceleyebilirsiniz.
Kaynaklar
Sıkça Sorulan Sorular
Yapılandırılmış JSON loglama uygulama performansını düşürür mü?
Doğru kütüphaneler ve asenkron yazma (non-blocking I/O) mimarisi kullanıldığında performans etkisi %1’in altındadır. Uygulama ana iş parçacığı (main thread) logu diske veya Elasticsearch sunucusuna göndermek için beklemez; JSON satırını standart çıktı akışına (stdout) veya bellek içi tampona bırakır. Arka planda çalışan hafif log ajanları (Fluent Bit, Vector veya Filebeat) bu çıktıları toplayıp sıkıştırarak merkezi log sunucusuna iletir.
Merkezi log sunucusunda (ELK / Loki) disk dolmasını önlemek için ne yapılmalıdır?
Kurumsal log yönetiminde Yaşam Döngüsü Politikası (Index Lifecycle Management - ILM) uygulanmalıdır. Son 7-14 günün logları hızlı arama için NVMe SSD diskli “Hot (Sıcak)” katmanda tutulur. 15 ile 90 gün arasındaki loglar sıkıştırılarak daha ekonomik olan “Warm/Cold (Ilık/Soğuk)” depolama katmanına taşınır. Yasal olarak 2 yıl saklanması zorunlu olan 5651 ve güvenlik denetim logları ise zaman damgalı ve yüksek sıkıştırmalı arşiv paketleri halinde soğuk nesne depolama (Object Storage) alanlarında muhafaza edilir.
Mikroservislerde her log satırında aynı alanların tekrar etmesi ağ trafiğini şişirmez mi?
JSON metin tabanlı olduğu için alan adları tekrar eder; ancak log toplayıcı ajanlar (Fluent Bit / Vector) logları merkezi sunucuya gönderirken Gzip veya Zstandard (zstd) sıkıştırma algoritmalarını kullanır. Tekrarlayan JSON anahtar adları (timestamp, level, serviceName, correlationId) sıkıştırma algoritmaları tarafından %85-%90 oranında küçültülür, böylece ağ bant genişliği üzerinde neredeyse hiçbir ek yük oluşturmaz.