Python'da logging ile Uygulama Günlüğü Nasıl Tutulur?

Python logging modülü neden print yerine kullanılır?

Küçük bir betik yazarken olan biteni ekrana print ile yazdırmak yeterli görünür. Betik zamanlanmış bir görev olarak sunucuda çalışmaya başladığında ise ekran yoktur; hata olduğunda ne olduğunu gösterecek bir iz de yoktur. Logging, bu izi sistemli biçimde bırakmanın yoludur ve Python'un standart kütüphanesinde hazır gelir.

Logging'in print'ten farkı şunlardır: • Her mesajın bir seviyesi vardır (DEBUG, INFO, WARNING, ERROR, CRITICAL). Hangi seviyenin görüneceğini kodu değiştirmeden ayarlarsınız • Mesajlar aynı anda hem ekrana hem dosyaya gidebilir • Her kayda zaman damgası, modül adı ve satır bilgisi otomatik eklenebilir • Hata durumunda hatanın tam izi (traceback) kayda dahil edilebilir • Dosya boyutu dolunca yeni dosyaya geçen döndürmeli kayıtlar tutulabilir • Kütüphaneler de aynı sistemi kullandığı için üçüncü taraf paketlerin mesajlarını da aynı yerde toplarsınız

Seviyeler bir önem sıralaması oluşturur. DEBUG geliştirme sırasında ayrıntılı bilgi içindir. INFO işlerin normal akışını anlatır: "dosya işlendi", "rapor gönderildi". WARNING beklenmeyen ama işi durdurmayan durumları işaretler. ERROR bir işlemin başarısız olduğunu, CRITICAL ise uygulamanın devam edemediğini gösterir. Canlı ortamda genellikle INFO ve üstü kaydedilir; sorun ararken geçici olarak DEBUG açılır.

Logging'in temel kavramları: logger, handler, formatter, seviye

Logging sisteminin mantığı birkaç kavram üzerine kuruludur. Logger, kod içinde mesaj gönderdiğiniz nesnedir; her modülde modülün adıyla bir logger almak yaygın uygulamadır, çünkü kayıtlarda mesajın nereden geldiği görünür. Handler, mesajın nereye gideceğini belirler: ekran, dosya, ağ üzerinden bir sunucu ya da e-posta. Formatter, mesajın nasıl görüneceğini belirler: zaman damgası, seviye, modül adı ve mesaj metni. Seviye ise hangi mesajların geçeceğini filtreler.

En basit kullanım tek bir yapılandırma çağrısıdır: seviyeyi, biçimi ve çıktı dosyasını bir kez belirlersiniz, sonra her yerde logger'a mesaj yollarsınız. Daha büyük projelerde yapılandırma ayrı bir sözlükte ya da dosyada tutulur; böylece betiği değiştirmeden seviyeyi ve çıktı yerini ayarlayabilirsiniz.

Mesaj yazarken değişkenleri metne birleştirmek yerine logger'ın biçim parametrelerini kullanmak daha doğrudur: logger mesajı yalnızca o seviye açıksa biçimlendirir, böylece kapalı seviyeler performansı etkilemez. Hata yakaladığınız yerde istisna bilgisini de kayda eklemek (traceback), sorunu sonradan çözmenin en değerli kaynağıdır.

Bir de kaçınılacak nokta vardır: kütüphane niteliğindeki kodda handler yapılandırmayın. Yapılandırmayı yalnızca uygulamanın giriş noktasında yapın; kütüphane kodu sadece logger alıp mesaj yazsın.

Bir betiğe loglama eklemek: örnek yapılandırma

Loglama yapılandırmasını betiğin başında tek yerde yapın, her modülde modül adıyla logger alın ve hata yakaladığınız yerde istisna ayrıntısını kayda ekleyin:

import logging

logging.basicConfig( level=logging.INFO, filename="betik.log", format="%(asctime)s %(levelname)s %(name)s: %(message)s", ) log = logging.getLogger(__name__)

def aktar(kayitlar): for kayit in kayitlar: try: gonder(kayit) except ConnectionError: log.exception("Hedef sisteme bağlanılamadı, kayıt=%s", kayit["kod"])

Hata durumunda dosyaya zaman damgası, seviye, modül adı, mesaj ve hatanın tam izi (traceback) yazılır. Değişkenleri metne birleştirmek yerine biçim parametrelerini (%s) kullanmak doğrudur; logger mesajı yalnızca o seviye açıksa biçimlendirir. İşin başında ve sonunda INFO kaydı düşün ("işlem başladı", "işlem bitti, şu kadar kayıt işlendi"), atlanan kayıtlar için WARNING yazın, dosya kaydını logging.handlers modülündeki döndürmeli işleyiciyle tutarak diskin dolmasını önleyin. Hassas veriyi (şifre, kart bilgisi, kimlik numarası, tam e-posta adresi) kayda hiç yazmayın ya da maskeleyin. Betiği bilerek hatalı girdiyle çalıştırın: log dosyasından kodu açmadan neyin, nerede ve neden başarısız olduğunu anlayabiliyorsanız loglama yeterlidir.

Örnek senaryo: gece çalışan veri aktarım betiği

Örneğin bir betik her gece bir sistemden sipariş verilerini çekip diğerine aktarıyor. Loglama yoksa bir sabah aktarımın tamamlanmadığı fark edilir ama nedeni bilinmez. Loglama varsa betik şunları kaydeder: başlangıç zamanı, kaynaktan kaç kayıt alındığı, her kayıt grubunun işlenmesinin sonucu, atlanan bozuk kayıtlar için WARNING ve kayıt kodu, hedef sisteme bağlanamadığında ERROR ve hatanın tam izi, bitişte toplam işlenen ve atlanan kayıt sayısı ile geçen süre.

Sabah ekip log dosyasına baktığında akışı bir hikâye gibi okur: iş başladı, belirli bir noktada ağ hatası alındı, yeniden denendi, başarılı oldu. Ya da yeniden denemeler tükendi, iş yarıda kaldı ve şu kayıt işlenmedi. Hangi kaydın eksik olduğu da bilindiği için yalnızca o kısım yeniden çalıştırılır.

Bu betik büyüdükçe loglar çok dosyaya dağılır. O noktada kayıtların merkezi bir yerde toplanıp aranabilir hale getirilmesi gerekir; bir olayın tüm adımlarını bir arada görmek için her çalışmaya bir kimlik numarası eklemek de aramayı kolaylaştırır.

Yapılandırılmış loglama: makinenin okuyabileceği kayıtlar

Klasik loglar insan okumak için yazılmış cümlelerdir. Sistem büyüdüğünde bu kayıtları aramak, filtrelemek ve saymak zorlaşır, çünkü bilgi serbest metnin içine gömülüdür. Yapılandırılmış loglamada her kayıt, alanları belli bir veri yapısıdır (çoğunlukla JSON): zaman, seviye, mesaj ve olaya özgü alanlar. "Sipariş işlendi" cümlesi yerine sipariş kodu, müşteri kodu, süre ve sonuç alanları ayrı ayrı yazılır.

Bu yaklaşımın faydası, kayıt arama ve analiz araçlarının alanlara göre sorgu çalıştırabilmesidir: "hata seviyesinde olan, şu müşteriyle ilgili, son saatteki tüm kayıtları getir" gibi. Python'da logging modülüne biçimlendirici ekleyerek ya da yapılandırılmış loglama kütüphanelerini kullanarak bu çıktıyı üretebilirsiniz.

Ayrıca, bir isteğin birden çok servis veya adım üzerinden geçtiği sistemlerde her kayda ortak bir korelasyon kimliği eklenir; böylece tek bir işlemin bütün izi tek sorguyla bulunur. Gizlilik de bu aşamada tasarımın parçasıdır: hangi alanların kayda yazılmayacağı baştan belirlenmeli, kişisel veriler maskelenmelidir. Maliyet de unutulmamalıdır; her şeyi ayrıntılı kaydetmek depolama ve arama maliyetini artırır.

Loglamayı işe yaramaz kılan hatalar

Loglama kolay görünür ama yanlış kurulduğunda ya işe yaramaz ya da zarar verir:

• Her şeyi print ile yazdırmak. Seviye, dosya ve zaman damgası kontrolü kaybolur.
• Seviyeleri karıştırmak. Her mesajı ERROR yazarsanız gerçek hatalar gürültüde kaybolur; her şeyi INFO yazarsanız önem ayrımı olmaz.
• Hatayı yutmak. Boş bir hata bloğu sorunu gizler. Yakaladığınız hatayı en azından kaydedin.
• Hassas veriyi kayda yazmak. Şifre, anahtar, kişisel veri loglara girerse bu dosyaya erişen herkes görür ve uyum sorunu doğar.
• Log dosyasını döndürmemek. Disk dolar, uygulama durur.
• Kayıtta bağlam bırakmamak. "Hata oluştu" mesajı işe yaramaz; hangi dosya, hangi kayıt, hangi parametre olduğunu yazın.
• Yapılandırmayı birden çok yerde yapmak. Mesajlar çift yazılır ya da hiç görünmez.
• Döngü içinde yoğun kayıt yazmak. Çok büyük hacimde ayrıntılı kayıt hem yavaşlatır hem maliyet çıkarır.
• Kayıtları hiç okumamak. Log, ancak izleme ve uyarı mekanizmasıyla birleşince değer üretir.

İyi bir ölçüt: gece yarısı gelen bir arıza uyarısında yalnızca log dosyasına bakarak sorunun nedenini ve etkilenen kayıtları bulabiliyor muyum?

Betik ve uygulama işleten ekipler için Mindset bağlamı

Mindset kataloğundaki Yapılandırılmış Loglama ve Uygulama Telemetrisi programı, loglamayı tek bir betiğin ötesine, sistem düzeyine taşır; Yapılandırılmış Log Şeması Tasarımı ve Korelasyon ve Dağıtık İzleme modülleri yapılandırılmış loglama bölümünün devamıdır. Uygulama geliştiren, sistem işleten ve otomasyon betikleri yazan ekipler için uygundur; kurumsal ekiplerde ortak log standardı oluşturmak isteyenler Maliyet, Gizlilik ve Standart Belgesi modülüyle ilgilenebilir.