Günlük kaydı: logging modülü

`print` neden yetmez: düzeyler, `basicConfig` ve biçimler, günlükçüler, işleyiciler ve biçimlendiriciler, `getLogger(__name__)` ile günlükçü hiyerarşisi, dosyaya yazmak ve `RotatingFileHandler`, `logger.exception`, `dictConfig` ile yapılandırma ve günlüğe asla yazılmaması gerekenler.

  • İleri
  • 22 dk
  • 12 soru
  • Ders 33 / 66

Bu derste öğreneceklerin

  • Bir ileti için doğru düzeyi seçmek ve düzey süzgecinin nasıl çalıştığını açıklamak
  • Günlükçüleri, işleyicileri ve biçimlendiricileri birleştirmek: konsol ve dosya için farklı düzeyler
  • İstisnaları logger.exception ile kaydetmek ve günlük dosyalarını döndürmek
  • Bir uygulamanın günlüğünü tek yerde dictConfig ile yapılandırmak

Bir rapor betiği her gece saat 3’te bir sunucuda çalışıyor. Bir sabah rapor yok. Ne oldu? print ile yazılan iletiler kimsenin bakmadığı bir ekrana gitti ve kayboldu. Betik bir günlük (log) tutsaydı, bir dosyada 2026-10-02 03:00:05 ERROR report: database is locked gibi bir satır olurdu. logging modülü Python’un standart günlük sistemidir; «Otomasyon betikleri» dersinde onunla kısaca tanıştın, şimdi onu ayrıntılı öğreneceğiz.

  • Düzeyler: önemsiz iletiler kodu değiştirmeden kapatılabilir.
  • Bağlam: zaman, modül, fonksiyon ve satır numarası kendiliğinden eklenir.
  • Hedefler: aynı ileti ekrana, bir dosyaya, e-postaya ya da bir sunucuya gidebilir.
  • Tek yerden yönetim: kütüphaneler günlük iletisi yazar, nasıl gösterileceğine uygulama karar verir.

Düzeyler

DüzeySayıNe zaman
DEBUG10geliştirici için ayrıntılar: değişkenler, adımlar
INFO20normal ilerleme: “rapor başladı”, “118 dosya kopyalandı”
WARNING30olağan dışı bir şey, ama iş sürüyor
ERROR40bir işlem başarısız oldu
CRITICAL50program çalışmayı sürdüremiyor
record is shown ⇔ level(record) ≥ level(logger) and level(record) ≥ level(handler)

Burada

level(record)
iletinin düzeyi: log.info → 20
level(logger)
günlükçünün etkin düzeyi (kendisininki ya da en yakın üst günlükçününki)
level(handler)
iletiyi çıkaran işleyicinin düzeyi

Eşik ne kadar düşükse o kadar çok ileti görünür. Kök günlükçünün varsayılan düzeyi WARNING olduğundan, yapılandırma olmadan info iletileri görünmez.

Python
import logging
import sys

logging.basicConfig(stream=sys.stdout, format='%(levelname)-8s| %(message)s', force=True)
log = logging.getLogger('demo')

for level in (logging.DEBUG, logging.INFO, logging.WARNING):
    log.setLevel(level)
    print(f'--- logger level {logging.getLevelName(level)} ({level})')
    log.debug('details for developers')
    log.info('normal progress')
    log.warning('something unusual')
Beklenen çıktı
--- logger level DEBUG (10)
DEBUG   | details for developers
INFO    | normal progress
WARNING | something unusual
--- logger level INFO (20)
INFO    | normal progress
WARNING | something unusual
--- logger level WARNING (30)
WARNING | something unusual
Çıktı tarayıcıda görünsün diye stream=sys.stdout yazıyoruz (varsayılan olarak günlük stderr akışına gider); force=True ise önceki çalıştırmalardan kalan yapılandırmanın yerini alır.

İletileri f-string ile değil, %s yer tutucuları ve ayrı argümanlarla yaz: log.info('copied %d files', n). Metin yalnızca ileti gerçekten çıkarılacağı zaman kurulur; günlük çözümleme araçları da aynı şablonlu iletileri gruplayabilir:

Python
import logging
import sys

logging.basicConfig(stream=sys.stdout, format='%(levelname)s %(message)s', force=True)
log = logging.getLogger('lazy')
log.setLevel(logging.INFO)


class Report:
    def __str__(self):
        print('  (building a long text...)')
        return 'big report'


log.debug('data: %s', Report())        # below INFO: the text is never built
log.debug(f'data: {Report()}')         # the f-string is built anyway
log.info('data: %s', Report())         # shown, so it is built once
Beklenen çıktı
  (building a long text...)
  (building a long text...)
INFO data: big report
İlk debug metni hiç kurmadı, f-string ise ileti atılmasına rağmen kurdu. Büyük nesnelerde ve sık çağrılan kodda bu fark hissedilir.

Okumaya devam etmek için ücretsiz kaydol

Dersin geri kalan bölümleri, test ve notlar Educora hesabıyla açılır. Kayıt bir dakika sürer; ilerlemen tüm cihazlarında saklanır.

basicConfig ve biçimler

logging.basicConfig(...) en basit kurulumdur: kök günlükçüye bir işleyici ve bir biçimlendirici ekler. Yalnızca bir kez çalışır; kökün zaten bir işleyicisi varsa sonraki çağrılar hiçbir şey yapmaz (force=True verilmedikçe). Bu yüzden onu programın giriş noktasında, if __name__ == '__main__': bloğunda çağır. Biçim dizesinde %(ad)s biçiminde alanlar bulunur:

AlanNe yazar
%(asctime)szaman (biçimi datefmt belirler)
%(levelname)sdüzeyin adı
%(name)sgünlükçünün adı
%(module)s, %(funcName)s, %(lineno)dmodül, fonksiyon, satır numarası
%(message)siletinin kendisi
Python
import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s %(levelname)s [%(name)s] %(funcName)s:%(lineno)d %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S',
)
log = logging.getLogger('shop')


def checkout(total):
    log.info('checkout total=%.2f', total)


checkout(42.5)

Beklenen çıktı

2026-10-03 17:38:15 INFO [shop] checkout:12 checkout total=42.50
Burada stream verilmedi; bu yüzden günlük stderr akışına gider. Zaman, kodu çalıştırdığın anı gösterecek; 12 numaralı satır log.info satırıdır.

Günlükçüler, işleyiciler ve biçimlendiriciler

Günlükçü, işleyici ve biçimlendiriciTanım

Günlükçü (logger), kodunun ileti gönderdiği adlı bir nesnedir (logging.getLogger('shop.orders')); aynı ad her zaman aynı nesneyi döndürür. İşleyici (handler) iletiyi hedefe ulaştırır: StreamHandler konsol, FileHandler dosya, RotatingFileHandler dönen dosyalar içindir. Biçimlendirici (formatter) bir kaydı bir metin satırına çevirir. Her işleyicinin kendi düzeyi ve biçimlendiricisi olabilir.

log.info('order 17')Logger 'shop.orders'INFO ≥ günlükçü düzeyi mi?StreamHandlerdüzey: WARNINGFileHandlerdüzey: DEBUGFormatter→ ekranFormatter→ app.log dosyasısonra kayıt üst günlükçülere gider:shop → root (propagate)

Günlükçü adları noktalarla bir hiyerarşi kurar: shop.orders, shop günlükçüsünün çocuğudur, shop ise kökün. Kendi düzeyi olmayan (NOTSET) bir günlükçü en yakın üst günlükçünün düzeyini alır. Bir kayıt önce günlükçünün kendi işleyicilerine, sonra (propagate = True olduğu sürece) üst günlükçülerin işleyicilerine gider; üst günlükçülerin düzeyleri yolda yeniden denetlenmez. Bu yüzden her modülde log = logging.getLogger(__name__) yazılır: günlükçü modülün adını alır (shop.orders) ve hiyerarşi paket yapısını izler.

Python
import logging
import sys

logging.basicConfig(stream=sys.stdout, level=logging.WARNING,
                    format='%(name)-14s %(levelname)-7s %(message)s', force=True)
logging.getLogger('shop').setLevel(logging.INFO)

orders = logging.getLogger('shop.orders')
payments = logging.getLogger('shop.payments')
print(orders.parent.name, orders.getEffectiveLevel(), payments.getEffectiveLevel())

orders.info('order 17 created')
payments.debug('card check details')
logging.getLogger('emails').info('newsletter sent')
logging.getLogger('emails').warning('mailbox full')
Beklenen çıktı
shop 20 20
shop.orders    INFO    order 17 created
emails         WARNING mailbox full
Kökün düzeyi WARNING, ama shop.orders günlükçüsünün INFO iletisi kökün işleyicisiyle yazdırıldı: düzey yalnızca iletinin oluştuğu günlükçüde (etkin düzey 20) denetlenir. emails düzeyini kökten alır (30); bu yüzden onun info iletisi atıldı.

Şimdi işleyicileri elle kuralım: konsola yalnızca uyarılar, dosyaya her şey gitsin. propagate = False, iletinin köke de ulaşıp ikinci kez yazdırılmasını önler:

Python
import logging
import sys

log = logging.getLogger('nightly')
log.setLevel(logging.DEBUG)
log.propagate = False
log.handlers.clear()                 # so that running the code again adds no duplicates

console = logging.StreamHandler(sys.stdout)
console.setLevel(logging.WARNING)
console.setFormatter(logging.Formatter('CONSOLE %(levelname)s: %(message)s'))

file = logging.FileHandler('nightly.log', mode='w', encoding='utf-8')
file.setLevel(logging.DEBUG)
file.setFormatter(logging.Formatter('%(levelname)-7s %(name)s %(message)s'))

log.addHandler(console)
log.addHandler(file)
log.debug('found 120 files')
log.info('copied 118 files')
log.warning('2 files skipped: permission denied')
file.close()

print('--- nightly.log:')
print(open('nightly.log', encoding='utf-8').read(), end='')
Beklenen çıktı
CONSOLE WARNING: 2 files skipped: permission denied
--- nightly.log:
DEBUG   nightly found 120 files
INFO    nightly copied 118 files
WARNING nightly 2 files skipped: permission denied

İstisnalar ve günlük dosyaları

Bir except bloğunun içinde log.exception('...') iletiyi ERROR düzeyinde yazar ve tam traceback’i ekler; hatanın nerede olduğu sonradan günlükten görülür. Diğer düzeylerde aynı işi exc_info=True yapar: log.warning('...', exc_info=True). Program istisnayı yakalar ve çalışmayı sürdürür («Hata yönetimi: try ve except» dersine bak):

Python
import logging

logging.basicConfig(level=logging.INFO, format='%(levelname)s %(name)s: %(message)s')
log = logging.getLogger('orders')


def average(total, count):
    return total / count


try:
    average(120, 0)
except ZeroDivisionError:
    log.exception('could not compute the average for order %d', 17)
log.info('the program keeps running')

Beklenen çıktı

ERROR orders: could not compute the average for order 17
Traceback (most recent call last):
  File "orders.py", line 12, in <module>
    average(120, 0)
    ~~~~~~~^^^^^^^^
  File "orders.py", line 8, in average
    return total / count
           ~~~~~~^~~~~~~
ZeroDivisionError: division by zero
INFO orders: the program keeps running
File "..." satırlarındaki yol, dosyanın nerede saklandığına bağlıdır; tarayıcıda bu ad <exec> olur.

Sürekli çalışan bir programın günlük dosyası diski doldurabilir. logging.handlers.RotatingFileHandler, dosya maxBytes sınırına ulaşınca onu app.log.1 olarak yeniden adlandırır (eskiler .2, .3 olur) ve yeni bir dosya açar; backupCount kaç eski dosyanın saklanacağını belirtir. TimedRotatingFileHandler ise dosyaları zamana göre, örneğin her gece döndürür.

Python
import logging
import os
from logging.handlers import RotatingFileHandler

log = logging.getLogger('sensor')
log.setLevel(logging.INFO)
log.propagate = False
log.handlers.clear()
handler = RotatingFileHandler('sensor.log', maxBytes=300, backupCount=2, encoding='utf-8')
handler.setFormatter(logging.Formatter('%(levelname)s %(message)s'))
log.addHandler(handler)

for i in range(1, 41):
    log.info('reading %02d: temperature %.1f', i, 20 + i / 10)
handler.close()

print(sorted(name for name in os.listdir() if name.startswith('sensor.log')))
with open('sensor.log', encoding='utf-8') as f:
    print(f.readlines()[-1].strip())
Beklenen çıktı
['sensor.log', 'sensor.log.1', 'sensor.log.2']
INFO reading 40: temperature 24.0
40 satır 300 baytlık dosyalara sığmadı: en yeni kayıtlar sensor.log dosyasında, eskilerden yalnızca iki dosya tutuldu, daha eskileri silindi.

dictConfig ile yapılandırma: mini proje

Büyük bir uygulamada günlük ayarları koda dağıtılmaz: bütün biçimlendiriciler, işleyiciler ve günlükçüler tek bir sözlükte tanımlanır ve programın giriş noktasında logging.config.dictConfig(...) ile uygulanır. Sözlük bir JSON ya da YAML dosyasından da okunabilir; düzeyi değiştirmek için kodu değiştirmek gerekmez. 'disable_existing_loggers': False mutlaka yaz: yoksa yapılandırmadan önce (örneğin içe aktarma sırasında) oluşturulan günlükçüler susturulur. Mini proje siparişleri işler: konsola INFO, dosyaya ise daha ayrıntılı biçimle DEBUG gider:

Python
import logging
import logging.config

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'short': {'format': '%(levelname)-7s %(name)s: %(message)s'},
        'full': {'format': '%(levelname)s|%(name)s|%(funcName)s|%(message)s'},
    },
    'handlers': {
        'console': {'class': 'logging.StreamHandler', 'stream': 'ext://sys.stdout',
                    'level': 'INFO', 'formatter': 'short'},
        'file': {'class': 'logging.FileHandler', 'filename': 'store.log', 'mode': 'w',
                 'encoding': 'utf-8', 'level': 'DEBUG', 'formatter': 'full'},
    },
    'loggers': {'store': {'level': 'DEBUG', 'handlers': ['console', 'file'], 'propagate': False}},
}
logging.config.dictConfig(LOGGING)
log = logging.getLogger('store.orders')


def process(order):
    log.debug('processing %s', order)
    if order['qty'] <= 0:
        log.warning('order %s skipped: qty=%s', order['id'], order['qty'])
        return 0
    total = order['qty'] * order['price']
    log.info('order %s: %.2f AZN', order['id'], total)
    return total


orders = [{'id': 1, 'qty': 2, 'price': 4.5}, {'id': 2, 'qty': 0, 'price': 9.9},
          {'id': 3, 'qty': 1, 'price': 15.0}]
log.info('revenue %.2f AZN', sum(process(o) for o in orders))
print(open('store.log', encoding='utf-8').readline(), end='')
Beklenen çıktı
INFO    store.orders: order 1: 9.00 AZN
WARNING store.orders: order 2 skipped: qty=0
INFO    store.orders: order 3: 15.00 AZN
INFO    store.orders: revenue 24.00 AZN
DEBUG|store.orders|process|processing {'id': 1, 'qty': 2, 'price': 4.5}
Konsolda DEBUG yok; dosyanın ilk satırı ise tam olarak fonksiyon adını da gösteren bir DEBUG kaydıdır. store.orders günlükçüsünün kendi işleyicisi yoktur; kayıtları üst günlükçü store işleyicilerine ulaşır.

Alıştırma

Günlüğü, yalnızca WARNING ve daha yüksek düzeydeki iletiler LEVEL: message biçiminde sys.stdout akışına yazılacak şekilde yapılandır. İleti yazan satırları değiştirme.

Alıştırma · Python
import logging
import sys

# configure logging here: stdout, level WARNING, format "LEVEL: message"

log = logging.getLogger('quiz')
log.debug('loading questions')
log.info('12 questions loaded')
log.warning('question 7 has no answer')
log.error('cannot save the results')
Beklenen çıktı
WARNING: question 7 has no answer
ERROR: cannot save the results

Alıştırma

safe_divide(a, b) başarıda INFO düzeyinde 10 / 4 = 2.5 yazıp sonucu döndürmeli, b 0 olduğunda ise WARNING düzeyinde cannot divide 3 by zero yazıp None döndürmeli. İletileri %s yer tutucularıyla kur.

Alıştırma · Python
import logging
import sys

logging.basicConfig(stream=sys.stdout, level=logging.INFO,
                    format='%(levelname)s %(name)s: %(message)s', force=True)
log = logging.getLogger('calc')


def safe_divide(a, b):
    # on success: log INFO "10 / 4 = 2.5" and return the result
    # if b is 0: log WARNING "cannot divide 3 by zero" and return None
    return a / b


print([safe_divide(10, 4), safe_divide(3, 0)])
Beklenen çıktı
INFO calc: 10 / 4 = 2.5
WARNING calc: cannot divide 3 by zero
[2.5, None]

Unutma

  • Düzeyler: DEBUG 10 < INFO 20 < WARNING 30 < ERROR 40 < CRITICAL 50; kökün varsayılan düzeyi WARNING’dir.
  • Her modülde logging.getLogger(__name__); adlar noktalı bir hiyerarşi kurar, kayıtlar üst günlükçülerin işleyicilerine iletilir.
  • İşleyici hedefi ve kendi düzeyini, biçimlendirici ise satırın görünüşünü belirler.
  • except içinde log.exception, ERROR ve traceback yazar; RotatingFileHandler günlük dosyalarının boyutunu sınırlar.
  • Yapılandırma bir kez, giriş noktasında: basicConfig ya da dictConfig (disable_existing_loggers: False); parola ve kişisel veri yazma.
Bu derste bir hata ya da yanlışlık mı gördün?

Kendini test et

12 soru. Her doğru cevap XP kazandırır.

Soru 1 / 12

Soru 1 / 12. Düzeylerin artan sırası hangisidir?