Her isteği dump etmek arızayı çözmez; gece gelen kesintide işe yarayan şey yeniden kurulabilir bir izdir. Bu rehberde uygulama loglama stratejisi ile neyin yazılacağını, şifre ve kişisel verinin neden loga düşmemesi gerektiğini sade adımlarla okursunuz.
Bir sipariş takılır, oturum düşer veya bir ödeme bildirimi iki kez gelir. O anda ekranda duran şey çoğu zaman devasa bir istek dökümü olur; aradığınız ise hangi kayıt, hangi adım, hangi sonuç kodudur. Bu rehberde uygulama loglama stratejisi, her isteği dump etmek yerine arızada işe yarayan iz bırakmayı ve şifre ile kişisel veriyi loga düşürmemeyi pratik adımlarla ele alır.
Dump, o anki gövdeyi olduğu gibi diske basmaktır. İz ise zaman, iş kimliği, sonuç ve bir sonraki kontrolü bağlayan kısa kayıttır. KepezWeb özel yazılım işlerinde logu arşiv değil teşhis aracı olarak ele alır: az, doğru ve bağlamsal satır, gürültülü dökümden daha hızlı yol gösterir.
Uygulama loglama stratejisi: dump değil iz
Bir HTTP isteğinin tamamını yazmak cazip görünür. Gövde, başlık, çerez, sorgu dizesi… hepsi “ileride lazım olur” diye durur. Gerçekte bu yığın üç zarar üretir.
Birincisi gürültüdür. Asıl hata, binlerce başarılı GET satırının altında kaybolur. İkincisi maliyettir: disk, indeks ve arama süresi şişer. Üçüncüsü sızıntıdır. Authorization başlığı, formdaki parola, teslimat adresi veya kart alanı loga karışabilir.
İyi bir uygulama loglama stratejisi şu soruyu sorar: Bu satır, gece gelen bir arızada hangi kararı hızlandırır? Cevabı yoksa yazılmaz. Cevabı “kayıt X, adım Y, sonuç Z” ise yazılır.
- Olayı yeniden sıralamak (ne zaman, hangi adımda koptu)
- Etkilenen iş kaydını bulmak (sipariş, sepet, bilet numarası)
- Aynı hatanın tekrarını ayırmak (tek seferlik mi, sağlayıcı mı, kod mu)
Dump dördüncü bir iş iddiasındadır: her şeyi sakla. Bu iddia teşhisi geciktirir. Üretimde varsayılan, gövdesiz ve olay adlı kayıttır.
Log, delil deposu değil teşhis cümlesidir. Cümlede kişi sırrı durmaz; iş kimliği ve sonuç durur.
Arızada işe yarayan log ne yazar
Arıza anında ekibin sorduğu sorular sabittir. Log bu sorulara cevap vermelidir; spekülasyonu değil yeniden kurulabilir bir sahneyi kurmalıdır.
Yazılması gereken çekirdek alanlar şunlardır:
- Zaman damgası (tercihen UTC, milisaniye)
- Ortam ve servis adı (örneğin prod, api-order)
- Önem seviyesi (info, warn, error)
- Sabit olay adı (order.payment.failed gibi bir fiil)
- Korelasyon veya istek kimliği
- İş kimliği (sipariş no, sepet no, iç kullanıcı no; doğrudan kişi verisi değil)
- Sonuç: başarı, iş kuralı reddi, teknik hata
- Kısa neden kodu (STOCK_SHORT, GATEWAY_TIMEOUT)
- Süre (isteğin milisaniye cinsinden maliyeti)
Örnek bir error satırı şöyle durur: sipariş 18402, ödeme adımı, sağlayıcı zaman aşımı, 1843 ms, request-id a8f3. Gövde yoktur. Kart yoktur. E-posta yoktur. Yine de nöbetteki kişi bir sonraki adımı bilir: o siparişi, o süreyi ve o sağlayıcıyı kontrol etmek.
İş olayları da aynı disiplini ister. “Sipariş oluşturuldu”, “iade onaylandı”, “stok düştü” bilgi seviyesinde, kimlik ve sonuçla yazılır. Her tıklama, her listeleme, her sağlık kontrolü yazılmaz. Sağlık kontrolünü error yapmak, gerçek kesintiyi gizler.
Hata nesnesinde yığın izi üretimde sınırlı tutulur. Hata tipi ve ilk birkaç kare çoğu zaman yeterlidir. Her 404 için tam zinciri basmak hem gürültüdür hem bazen istek verisini satıra taşır. Aynı istisnayı döngüde bin kez yazmak da ayrı bir hatadır: bir kez error, ardından sayaç ile özetleyin.
Teşhisi hızlandıran kısa cümle
Satırı bir insan okuyabilmelidir. “Null somewhere” yetmez. “Ödeme onayında sağlayıcı 504, sipariş 18402, deneme 2” yeter. Alan adları ekip içinde tek sözlükte dursun: event, order_id, duration_ms, result. Aynı olayı her geliştiricinin başka fiille yazması, aramayı bozar.
Loga düşmemesi gereken şifre ve kişisel veri
Kural nettir: kimlik doğrulama sırrı, ödeme sırrı ve kişiyi doğrudan teşhis eden veri loga yazılmaz. “Bir kez debug için” istisnası üretimde yoktur. Debug oturumu bile maskeleme olmadan kapanmalıdır.
Yazılmayanlar:
- Parola, PIN, OTP, yedek kod
- Çerez, oturum jetonu, yenileme jetonu, API anahtarı
- Authorization ve Cookie başlıklarının değeri
- Kart numarası, CVV, son kullanma; maskeleme bahanesiyle tam kart verisi
- TCKN, vergi kimliği, doğum tarihi, tam adres, telefon, e-posta
- Sağlık veya özel nitelikli veri
- Ham istek ve cevap gövdesi (özellikle form POST ve bildirim gövdesi)
- Yüklenen kimlik görüntüsü, fatura dosyası, serbest metin içerik
Kişisel verinin logda durması hem sızıntı hem uyum riski doğurur. Yedek kopya, destek ekranı ve hata izleme aracı aynı riskin parçasıdır. Yasal çerçevenizi hukuk danışmanınızla netleştirin; operasyon kuralı ise basittir: logda kişi değil iş kimliği durur.
Maskeleme yanıltmasın. E-postanın ilk harfini bırakmak hâlâ kişisel veridir. Teşhis “kullanıcı 9021” ile yapılır. İletişim kanalı ayrı, erişimi kısıtlı bir ekranda açılır. IP adresini her satıra yazmak da çoğu senaryoda gereksizdir; gerçekten kötüye kullanım incelemesi varsa ayrı, amaçlı bir erişim kaydı düşünülür.
Üçüncü taraf kütüphaneler varsayılan olarak gövdeyi yazabilir. Ödeme SDK’sı, HTTP istemcisi ve hata izleme aracı kurulurken istek gövdesi yakalama kapatılır. Aksi halde sizin yazmadığınız satır, sizin diskinizde durur. PHP tarafında var_dump veya print_r ile gövdeyi error_log’a basmak, özel PHP/MySQL yazılım işinde bile üretim alışkanlığı olmamalıdır.
| Kayıt türü | Yazılır | Yazılmaz |
|---|---|---|
| Kimlik doğrulama | İç kullanıcı no, sonuç, neden kodu | Parola, jeton, çerez, OTP |
| Sipariş ve sepet | Sipariş no, adım, stok/ödeme sonucu | Adres, telefon, e-posta, not alanı |
| Ödeme ve bildirim | Olay tipi, deneme sayısı, imza geçerli/geçersiz | Ham gövde, kart verisi, gizli anahtar |
| Uygulama hatası | Hata tipi, kısa yığın, istek kimliği | Form POST, dosya içeriği, tam başlık listesi |
| Kenar erişim kaydı | Yöntem, yol, durum kodu, süre, korelasyon | Authorization değeri, query içindeki jeton |
Seviye, gürültü ve üretim kuralı
Seviye, “ne kadar konuşayım” değil “kime haber vereyim” kararıdır. Her satırı error yapmak, gerçek kesintiyi görünmez kılar.
- DEBUG: yerel ve geçici. Üretimde kapalı. SQL metni ve tam başlık listesi burada bile maskelenir.
- INFO: işin ilerlediğini gösteren seyrek olay. Sipariş alındı, etiket basıldı.
- WARN: iş bitti ama sapma var. Yeniden deneme, yavaş sağlayıcı, eksik isteğe bağlı alan.
- ERROR: kullanıcı veya para etkilendi, insan bakmalı. Ödeme alınamadı, stok düşmedi, yazılamadı.
İş kuralı reddi çoğu zaman exception değildir. Yanlış kupon, yetersiz stok, eksik teslimat bölgesi kullanıcıya zaten söylenir; bunu error yapmak gece alarmını boşa harcar. Info veya warn yeter. Teknik kopma (zaman aşımı, kısıt, veri yazılamaması) error’dur.
Üretim kuralı sade tutulur: varsayılan info, hata yolu error, gövde dump yok. Geçici debug, belirli bir istek kimliğine bağlanır ve kapanışı unutulmaz. Bayrağı açık unutmak, politikayı fiilen iptal eder.
Küçük ekiplerde bu kuralı yayın hattına bağlamak işe yarar. Derleme ve test kapısından geçen kod, log seviyesini de taşır. CI/CD pipeline kısa bir otomatik hat olarak kurulduğunda, kontrol listesine iki madde eklenir: üretim yapılandırmasında debug kapalı mı, örnek ortam dosyasında gizli anahtar yok mu? Pipeline logu ile uygulama logu da karışmamalıdır. Derleme çıktısı sır, jeton ve müşteri verisi basmamalıdır.
Korelasyon kimliği ile isteği bağlamak
Tek satır yetmez. Bir sipariş API, kuyruk, e-posta ve kargo servisine dağılır. Dağılan iz aynı kimlikle birleşmezse ekip yeniden dump’a döner.
Her dış isteğe bir korelasyon kimliği verin. Ağ geçidi üretirse alt servisler aynı değeri taşır. Yoksa ilk servis üretir ve yanıt başlığında geri verir. Destek ekibi “şu request-id” diye sorabilmelidir. Aynı değer, kullanıcıya gösterilen kısa hata kodunda da durabilir. “Bir şeyler ters gitti” yerine ortak bir kod, dump olmadan teşhisi mümkün kılar.
Yapılandırılmış satır (örneğin JSON satır) aramayı kolaylaştırır. Serbest metin “timeout oldu galiba” cümlesi indekslenmez. Olay adı, iş kimliği ve süre ayrı alanlarda dursun. Metin alanı varsa kısa ve maskelenmiş olsun; gövdeyi oraya yapıştırmayın.
Örnek bir akış: tarayıcı istek atar, API request-id üretir, ödeme servisi aynı id ile timeout yazar, kuyruk aynı id ile yeniden denemeyi info basar, destek aynı id ile sipariş kaydını açar. Hiçbir adımda kart veya adres satıra girmez. Teşhis yine tamamlanır.
Ödeme, webhook ve üçüncü taraf izi
Ödeme ve kargo bildirimi, logda en çok sızdırılan alandır. Gövdeyi olduğu gibi yazmak kart ve adres taşır. İmza başlığının değerini yazmak ise doğrulama sırrını zayıflatır.
Bildirimde yazılacaklar sınırlıdır: sağlayıcı adı, olay tipi, teslimat denemesi, sizin döndüğünüz HTTP durumu, imzanın geçerli veya geçersiz olduğu bilgisi (değer değil), iş kimliği. Ham gövde ve gizli anahtar yazılmaz. KepezWeb tarafında ödeme ve bildirim izi gövdesiz tasarlanır; teşhis olay tipi ve iş numarasıyla kurulur.
Webhook nedir yazısı imza kontrolü, tekrar teslimat ve sıra dışı olayı adım adım ayırır. Aynı disiplin loga da uygulanır: tekrar gelen bildirimi dump etmezsiniz; “event_id X, deneme 3, sonuç duplicate” yazarsınız. Zaman aşımında her deneme ayrı satırdır. Böylece “üç kez denendi, dördüncüsünde 200” cümlesi gövde olmadan kurulur.
Dış sağlayıcı hata metnini olduğu gibi yazmadan önce tarayın. Bazı ağ geçitleri yanıtta e-posta veya jeton döndürür. Sizin neden kodunuz yeter; sağlayıcı cümlesi ancak kısaltılmış ve maskelenmiş haliyle warn veya error’a eklenir.
Uygulamaya koyulacak kısa kontrol listesi
- Olay sözlüğünü yazın: hangi fiil info, hangisi error.
- İş kimliği ve korelasyon kimliğini zorunlu alan yapın.
- HTTP istemcisi, ödeme SDK’sı ve hata izlemede gövde yakalamayı kapatın.
- Başlık kara listesi tutun: Authorization, Cookie, Set-Cookie.
- Üretimde debug’ı varsayılan kapalı bırakın; açılışını zamanla sınırlayın.
- Destek ekranının logu ham göstermediğini kontrol edin.
- Yeni bir entegrasyon eklenince “bu gövde loga düşer mi?” sorusunu yayın kapısına koyun.
Sıkça Sorulan Sorular
Her HTTP isteğini uygulama loguna yazmak gerekir mi?
Gerekmez. Kenar erişim kaydı ile uygulama logu ayrı işlerdir. Kenar yöntem, yol, durum kodu, süre ve korelasyon kimliğini tutabilir. Uygulama iş olayını ve hatayı tutar. İkisinin de gövdeyi yazmasına gerek yoktur. Sağlık kontrolü ve statik dosya gürültüsünü uygulama logundan çıkarın.
Hata izleme aracına tam istek göndermek güvenli mi?
Hayır. APM ve hata izleme, logun bir kopyasıdır. Gövde yakalama, çerez ve form alanı varsayılanı kapatılır. Aynı maskeleme kuralı orada da geçerlidir. Araç “otomatik bağlam” vaat ediyorsa bağlamın içinde ne olduğunu tek tek kontrol edin.
Geliştirme ortamındaki ayrıntılı log üretimde açılmalı mı?
Sürekli açılmamalıdır. Gerekirse kısa süreli, belirli bir istek kimliğine bağlı ve kapanışı net bir bayrakla açılır. “Bir gece debug” gerekçesi, sızıntıların sık tekrarlanan hikâyesidir. Yerelde bile parola ve jeton basılmamalıdır.
Kartın son dört hanesini yazmak yeterli maskeleme midir?
Operasyonel varsayılan yazmamaktır. Teşhis için ödeme niyeti kimliği, sağlayıcı referansı ve sipariş numarası yeterlidir. Kart verisi logda durmamalıdır. Ağ kuralları ve risk iştahı değişebilir; şüphede logdan çıkarın, ödeme panelinden bakın.
Logu kısa tutarsak teşhis imkânı biter mi?
Teşhis sonsuz arşivle değil doğru izle yaşar. İş kimliği ve korelasyon destek kaydında da durabilir. Saklama süresini iş ihtiyacı ve uyum çerçevesine göre belirlersiniz; “hepsini sonsuza dek tut” hem maliyet hem risk üretir. Silinen dump’un yerini, iyi yazılmış olay satırı doldurur.
Log politikası yazılımın görünmeyen bir parçasıdır; sonradan eklenince hem gürültü hem sızıntı birikir. KepezWeb, yazılım geliştirme işlerinde teşhis edilebilir kayıt ve güvenli veri akışını baştan tasarlar. Uygulamanızda neyin yazılıp yazılmayacağını netleştirmek için teklif alın.
