Логирование: модуль logging

Почему `print` недостаточно: уровни, `basicConfig` и форматы, логгеры, обработчики и форматтеры, иерархия логгеров и `getLogger(__name__)`, запись в файл и `RotatingFileHandler`, `logger.exception`, настройка через `dictConfig` и то, что нельзя писать в журнал.

  • Продвинутый
  • 22 мин
  • 12 вопросов
  • Урок 33 из 66

В этом уроке ты узнаешь

  • Выбирать уровень сообщения и объяснять, как работает фильтр по уровням
  • Связывать логгеры, обработчики и форматтеры: разные уровни для консоли и файла
  • Записывать исключения через logger.exception и ротировать файлы журнала
  • Настраивать журнал приложения в одном месте через dictConfig

Скрипт отчёта каждую ночь в 3 часа запускается на сервере. Однажды утром отчёта нет. Что случилось? Сообщения, напечатанные через print, ушли на экран, на который никто не смотрит, и пропали. Если бы скрипт вёл журнал (лог), в файле была бы строка вроде 2026-10-02 03:00:05 ERROR report: database is locked. Модуль logging — стандартная система журналирования Python; в уроке «Скрипты автоматизации» ты бегло с ним познакомился, а теперь изучим его как следует.

  • Уровни: неважные сообщения можно отключить, не меняя код.
  • Контекст: время, модуль, функция и номер строки добавляются автоматически.
  • Назначения: одно и то же сообщение может идти на экран, в файл, на почту или сервер.
  • Управление из одного места: библиотеки пишут сообщения, а приложение решает, как их показывать.

Уровни

УровеньЧислоКогда
DEBUG10подробности для разработчика: переменные, шаги
INFO20обычный ход работы: «отчёт начат», «скопировано 118 файлов»
WARNING30что-то необычное, но работа продолжается
ERROR40операция не удалась
CRITICAL50программа не может продолжать работу
record is shown ⇔ level(record) ≥ level(logger) and level(record) ≥ level(handler)

Где

level(record)
уровень сообщения: log.info → 20
level(logger)
действующий уровень логгера (свой или ближайшего родителя)
level(handler)
уровень обработчика, который выводит сообщение

Чем ниже порог, тем больше сообщений видно. Уровень корневого логгера по умолчанию — WARNING, поэтому без настройки сообщения info не видны.

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')
Ожидаемый результат
--- 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, чтобы вывод был виден в браузере (по умолчанию журнал идёт в stderr), а force=True заменяет настройку, оставшуюся от прошлых запусков.

Пиши сообщения через заполнители %s и отдельные аргументы, а не через f-строки: log.info('copied %d files', n). Текст собирается только тогда, когда сообщение действительно выводится, а инструменты анализа журналов могут группировать сообщения с одинаковым шаблоном:

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
Ожидаемый результат
  (building a long text...)
  (building a long text...)
INFO data: big report
Первый debug текст так и не собрал, а f-строка собрала его, хотя сообщение было отброшено. Для больших объектов и часто вызываемого кода разница заметна.

Чтобы читать дальше, зарегистрируйся бесплатно

Остальные разделы урока, тест и заметки открываются с аккаунтом Educora. Регистрация занимает минуту, а прогресс сохраняется на всех твоих устройствах.

basicConfig и форматы

logging.basicConfig(...) — простейшая настройка: она добавляет корневому логгеру один обработчик и форматтер. Срабатывает она только один раз — если у корня уже есть обработчик, следующие вызовы ничего не делают (если не указан force=True). Поэтому вызывай её в точке входа программы, в блоке if __name__ == '__main__':. В строке формата — поля вида %(имя)s:

ПолеЧто выводит
%(asctime)sвремя (формат задаёт datefmt)
%(levelname)sназвание уровня
%(name)sимя логгера
%(module)s, %(funcName)s, %(lineno)dмодуль, функция, номер строки
%(message)sсамо сообщение
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)

Ожидаемый результат

2026-10-03 17:38:15 INFO [shop] checkout:12 checkout total=42.50
Здесь stream не указан, поэтому журнал идёт в stderr. Время будет моментом твоего запуска, а номер строки 12 — это строка с log.info.

Логгеры, обработчики и форматтеры

Логгер, обработчик и форматтерОпределение

Логгер — именованный объект, которому код отправляет сообщения (logging.getLogger('shop.orders')); одно и то же имя всегда возвращает один и тот же объект. Обработчик (handler) доставляет сообщение по назначению: StreamHandler — консоль, FileHandler — файл, RotatingFileHandler — сменяемые файлы. Форматтер превращает запись в строку текста. У каждого обработчика могут быть свой уровень и свой форматтер.

log.info('order 17')Logger 'shop.orders'INFO ≥ уровня логгера?StreamHandlerуровень: WARNINGFileHandlerуровень: DEBUGFormatter→ экранFormatter→ файл app.logзатем запись передаётся родителям:shop → root (propagate)

Имена логгеров через точки образуют иерархию: shop.orders — потомок shop, а shop — потомок корня. Логгер без своего уровня (NOTSET) берёт уровень ближайшего родителя. Запись сначала идёт к собственным обработчикам логгера, а затем (пока propagate = True) к обработчикам родителей — уровни родителей по пути заново не проверяются. Поэтому в каждом модуле пишут log = logging.getLogger(__name__): логгер получает имя модуля (shop.orders), а иерархия повторяет структуру пакетов.

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')
Ожидаемый результат
shop 20 20
shop.orders    INFO    order 17 created
emails         WARNING mailbox full
Уровень корня — WARNING, но сообщение INFO от shop.orders напечатал обработчик корня: уровень проверяется только у логгера, где сообщение создано (действующий уровень 20). emails наследует уровень корня (30), поэтому его info отброшено.

Теперь соберём обработчики вручную: на консоль — только предупреждения, в файл — всё. propagate = False не даёт сообщению дойти ещё и до корня и напечататься второй раз:

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='')
Ожидаемый результат
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

Исключения и файлы журнала

Внутри блока except вызов log.exception('...') пишет сообщение уровня ERROR и добавляет полный traceback — потом по журналу видно, где случилась ошибка. Для других уровней то же делает exc_info=True: log.warning('...', exc_info=True). Программа перехватывает исключение и продолжает работу (см. «Обработка ошибок: try и except»):

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')

Ожидаемый результат

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 "..." зависит от того, где лежит файл; в браузере имя будет <exec>.

Журнал постоянно работающей программы может заполнить диск. logging.handlers.RotatingFileHandler, когда файл достигает maxBytes, переименовывает его в app.log.1 (более старые становятся .2, .3) и открывает новый; backupCount задаёт, сколько старых файлов хранить. TimedRotatingFileHandler меняет файлы по времени, например каждую ночь.

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())
Ожидаемый результат
['sensor.log', 'sensor.log.1', 'sensor.log.2']
INFO reading 40: temperature 24.0
40 строк не уместились в файлы по 300 байт: самые новые записи в sensor.log, из старых хранятся только два файла, остальные удалены.

Настройка через dictConfig: мини-проект

В большом приложении настройки журнала не разбрасывают по коду: все форматтеры, обработчики и логгеры описывают в одном словаре и применяют в точке входа через logging.config.dictConfig(...). Словарь можно читать и из файла JSON или YAML — чтобы поменять уровень, код менять не нужно. Обязательно пиши 'disable_existing_loggers': False: иначе логгеры, созданные до настройки (например, при импорте), замолчат. Мини-проект обрабатывает заказы: на консоль идёт INFO, а в файл — DEBUG в более подробном формате:

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='')
Ожидаемый результат
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, а первая строка файла — как раз запись DEBUG, где видно и имя функции. У логгера store.orders своих обработчиков нет — записи доходят до обработчиков родителя store.

Задание

Настрой журнал так, чтобы в sys.stdout выводились только сообщения уровня WARNING и выше в формате LEVEL: message. Строки, которые пишут сообщения, не меняй.

Задание · 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')
Ожидаемый результат
WARNING: question 7 has no answer
ERROR: cannot save the results

Задание

safe_divide(a, b) при успехе должна записать 10 / 4 = 2.5 на уровне INFO и вернуть результат, а при b, равном 0, — записать cannot divide 3 by zero на уровне WARNING и вернуть None. Сообщения собирай через заполнители %s.

Задание · 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)])
Ожидаемый результат
INFO calc: 10 / 4 = 2.5
WARNING calc: cannot divide 3 by zero
[2.5, None]

Запомни

  • Уровни: DEBUG 10 < INFO 20 < WARNING 30 < ERROR 40 < CRITICAL 50; уровень корня по умолчанию — WARNING.
  • В каждом модуле — logging.getLogger(__name__); имена через точку образуют иерархию, записи передаются обработчикам родителей.
  • Обработчик задаёт назначение и свой уровень, форматтер — вид строки.
  • log.exception внутри except пишет ERROR и traceback; RotatingFileHandler ограничивает размер файлов журнала.
  • Настройка — один раз, в точке входа: basicConfig или dictConfig (disable_existing_loggers: False); пароли и персональные данные не пиши.
Заметил ошибку или неточность в уроке?

Проверь себя

Вопросов: 12. Каждый правильный ответ приносит XP.

Вопрос 1 / 12

Вопрос 1 / 12. Каков порядок уровней по возрастанию?