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üzey | Sayı | Ne zaman |
|---|---|---|
DEBUG | 10 | geliştirici için ayrıntılar: değişkenler, adımlar |
INFO | 20 | normal ilerleme: “rapor başladı”, “118 dosya kopyalandı” |
WARNING | 30 | olağan dışı bir şey, ama iş sürüyor |
ERROR | 40 | bir işlem başarısız oldu |
CRITICAL | 50 | program çalışmayı sürdüremiyor |
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.
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
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:
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 onceBeklenen çıktı
(building a long text...) (building a long text...) INFO data: big report
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.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:
| Alan | Ne yazar |
|---|---|
%(asctime)s | zaman (biçimi datefmt belirler) |
%(levelname)s | düzeyin adı |
%(name)s | günlükçünün adı |
%(module)s, %(funcName)s, %(lineno)d | modül, fonksiyon, satır numarası |
%(message)s | iletinin kendisi |
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
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.
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.
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
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:
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):
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 runningFile "..." 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.
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
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:
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}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.
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.
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.
exceptiçindelog.exception,ERRORve traceback yazar;RotatingFileHandlergünlük dosyalarının boyutunu sınırlar.- Yapılandırma bir kez, giriş noktasında:
basicConfigya dadictConfig(disable_existing_loggers: False); parola ve kişisel veri yazma.