logging — Logging facility for Python

Вихідний код: Lib/logging/__init__.py

Important

Ця сторінка містить довідкову інформацію про API. Інформацію про підручники та обговорення більш складних тем див

• Основний посібник

• Розширений посібник

• Кулінарна книга журналювання

---

Цей модуль визначає функції та класи, які реалізують гнучку систему реєстрації подій для програм і бібліотек.

Ключовою перевагою використання API журналювання, що надається стандартним бібліотечним модулем, є те, що всі модулі Python можуть брати участь у журналюванні, тому ваш журнал програми може містити ваші власні повідомлення, інтегровані з повідомленнями від сторонніх модулів.

The module provides a lot of functionality and flexibility. If you are unfamiliar with logging, the best way to get to grips with it is to see the tutorials (see the links on the right).

The basic classes defined by the module, together with their functions, are listed below.

• Логери відкривають інтерфейс, який безпосередньо використовує код програми.

• Обробники надсилають записи журналу (створені реєстраторами) у відповідне місце призначення.

• Фільтри забезпечують точніші засоби для визначення того, які записи журналу виводити.

• Засоби форматування вказують макет записів журналу в кінцевому виведенні.

Логер об’єктів

Реєстратори мають такі атрибути та методи. Зауважте, що Логери НІКОЛИ не повинні створюватися безпосередньо, а завжди через функцію рівня модуля logging.getLogger(name). Кілька викликів getLogger() з однаковою назвою завжди повертатимуть посилання на той самий об’єкт Logger.

The name is potentially a period-separated hierarchical value, like foo.bar.baz (though it could also be just plain foo, for example). Loggers that are further down in the hierarchical list are children of loggers higher up in the list. For example, given a logger with a name of foo, loggers with names of foo.bar, foo.bar.baz, and foo.bam are all descendants of foo. The logger name hierarchy is analogous to the Python package hierarchy, and identical to it if you organise your loggers on a per-module basis using the recommended construction logging.getLogger(__name__). That’s because in a module, __name__ is the module’s name in the Python package namespace.

class logging.Logger

propagate

Якщо цей атрибут оцінюється як істина, події, зареєстровані в цьому реєстраторі, будуть передані обробникам реєстраторів вищого рівня (предків), на додаток до будь-яких обробників, приєднаних до цього реєстратора. Повідомлення передаються безпосередньо до обробників попередніх реєстраторів - ні рівень, ні фільтри попередніх реєстраторів, про які йдеться.

Якщо це значення має значення false, повідомлення журналу не передаються до обробників попередніх реєстраторів.

Напишіть це на прикладі: якщо атрибут propagate реєстратора під назвою A.B.C має значення true, будь-яка подія, зареєстрована в A.B.C через виклик методу, наприклад logging.getLogger('A.B.C') .error(...) [за умови передачі цього рівня реєстратора та налаштувань фільтра] буде передано по черзі будь-яким обробникам, приєднаним до реєстраторів з назвами A.B, A і кореневому реєстратору після першого передається будь-яким обробникам, приєднаним до A.B.C. Якщо будь-який реєстратор у ланцюжку A.B.C, A.B, A має атрибут propagate, встановлений на false, то це останній реєстратор, обробникам якого пропонується подія для обробки, і на цьому розповсюдження припиняється.

Конструктор встановлює цьому атрибуту значення True.

Примітка

Якщо ви приєднаєте обробник до реєстратора і одного або кількох його предків, він може створювати той самий запис кілька разів. Загалом, вам не потрібно приєднувати обробник до кількох реєстраторів — якщо ви просто приєднаєте його до відповідного реєстратора, який є найвищим в ієрархії реєстратора, тоді він бачитиме всі події, зареєстровані всіма нащадками реєстраторів, за умови, що вони поширюються параметр залишається встановленим на True. Поширеним сценарієм є приєднання обробників лише до кореневого реєстратора, а розповсюдження подбає про решту.

setLevel(level)

Встановлює порогове значення для цього реєстратора на рівень. Повідомлення журналу, менш суворі, ніж рівень, ігноруватимуться; Повідомлення журналювання, які мають рівень серйозності рівень або вищий, будуть випущені будь-яким обробником або обробниками, які обслуговують цей реєстратор, якщо рівень серйозності обробника не встановлено на вищий рівень серйозності, ніж рівень.

Коли реєстратор створюється, рівень встановлюється на NOTSET (що спричиняє обробку всіх повідомлень, коли реєстратор є кореневим реєстратором, або делегування батьківському, якщо реєстратор є некореневим). Зверніть увагу, що кореневий реєстратор створюється з рівнем WARNING.

Термін «делегування батьківському» означає, що якщо реєстратор має рівень NOTSET, його ланцюжок реєстраторів предків обходиться, доки не буде знайдено предка з рівнем, відмінним від NOTSET, або досягнуто кореня.

Якщо знайдено предка з рівнем, відмінним від NOTSET, тоді цей рівень предка розглядається як ефективний рівень реєстратора, з якого почався пошук предка, і використовується для визначення того, як обробляється подія журналювання.

Якщо кореневий доступ досягнутий і він має рівень NOTSET, то всі повідомлення будуть оброблені. В іншому випадку кореневий рівень буде використано як ефективний рівень.

Перегляньте Рівні реєстрації список рівнів.

Змінено в версії 3.2: Параметр level тепер приймає рядкове представлення рівня, наприклад «INFO», як альтернативу цілим константам, таким як INFO. Однак зауважте, що рівні внутрішньо зберігаються як цілі числа, а такі методи, як, наприклад, getEffectiveLevel() і isEnabledFor() повертатимуть/очікуватимуть передачу цілих чисел.

isEnabledFor(level)

Вказує, чи буде оброблено повідомлення рівня серйозності цим реєстратором. Цей метод спочатку перевіряє рівень модуля, встановлений logging.disable(level), а потім ефективний рівень реєстратора, визначений getEffectiveLevel().

getEffectiveLevel()

Вказує ефективний рівень для цього реєстратора. Якщо значення, відмінне від NOTSET, було встановлено за допомогою setLevel(), воно повертається. В іншому випадку ієрархія переміщається до кореня, доки не буде знайдено значення, відмінне від NOTSET, і це значення повертається. Значення, що повертається, є цілим числом, зазвичай одне з logging.DEBUG, logging.INFO тощо.

getChild(suffix)

Повертає реєстратор, який є нащадком цього реєстратора, як визначено суфіксом. Таким чином, logging.getLogger('abc').getChild('def.ghi') повертатиме той самий реєстратор, який повертає logging.getLogger('abc.def.ghi'). Це зручний метод, корисний, коли батьківський реєстратор називається, наприклад, __name__, а не літеральний рядок.

Нове в версії 3.2.

debug(msg, *args, **kwargs)

Записує повідомлення з рівнем DEBUG у цьому реєстраторі. msg — це рядок формату повідомлення, а args — це аргументи, які об’єднуються в msg за допомогою оператора форматування рядка. (Зауважте, що це означає, що ви можете використовувати ключові слова в рядку формату разом із одним аргументом словника.) Операція форматування % не виконується для msg, якщо не надано args.

У kwargs є чотири аргументи ключових слів, які перевіряються: exc_info, stack_info, stacklevel і extra.

Якщо exc_info не оцінюється як false, це спричиняє додавання інформації про винятки до повідомлення журналу. Якщо надано кортеж винятків (у форматі, який повертає sys.exc_info()) або екземпляр винятку, він використовується; інакше sys.exc_info() викликається для отримання інформації про винятки.

Другим необов’язковим ключовим аргументом є stack_info, який за умовчанням має значення False. Якщо значення true, інформація про стек додається до повідомлення журналу, включаючи фактичний виклик журналу. Зауважте, що це інша інформація про стек, яка відображається за допомогою exc_info: перша – це кадри стеку від нижньої частини стеку до виклику журналювання в поточному потоці, тоді як остання – це інформація про кадри стеку, які були переглянуті. unwind, після винятку, під час пошуку обробників винятків.

Ви можете вказати stack_info незалежно від exc_info, наприклад. щоб просто показати, як ви дійшли до певної точки у своєму коді, навіть якщо винятків не було викликано. Фрейми стека друкуються після рядка заголовка, який говорить:

Stack (most recent call last):

Це імітує Traceback (останній останній виклик):, який використовується під час відображення кадрів винятків.

Третій необов’язковий аргумент ключового слова — stacklevel, який за замовчуванням має значення «1». Якщо більше 1, відповідна кількість кадрів стека пропускається під час обчислення номера рядка та назви функції, встановленої в LogRecord, створеному для події журналювання. Це можна використовувати в помічниках журналювання, щоб ім’я функції, ім’я файлу та номер рядка були записані не для допоміжної функції/методу, а для її викликаючого. Назва цього параметра відображає еквівалентну назву в модулі warnings.

Четвертий аргумент ключового слова — extra, який можна використовувати для передачі словника, який використовується для заповнення __dict__ LogRecord, створеного для події журналювання, атрибутами, визначеними користувачем. Потім ці настроювані атрибути можна використовувати як завгодно. Наприклад, їх можна включити до зареєстрованих повідомлень. Наприклад:

FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)

надрукував би щось подібне

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

The keys in the dictionary passed in extra should not clash with the keys used by the logging system. (See the Formatter documentation for more information on which keys are used by the logging system.)

Якщо ви вирішите використовувати ці атрибути в зареєстрованих повідомленнях, вам потрібно бути обережними. У наведеному вище прикладі, наприклад, Formatter було налаштовано за допомогою рядка формату, який очікує „clientip“ і „user“ у словнику атрибутів LogRecord. Якщо вони відсутні, повідомлення не буде зареєстровано, оскільки виникне виняток форматування рядка. Тому в цьому випадку вам завжди потрібно передавати додатковий словник за допомогою цих ключів.

Хоча це може дратувати, ця функція призначена для використання в особливих умовах, наприклад, на багатопоточних серверах, де той самий код виконується в багатьох контекстах, і цікаві умови, які виникають, залежать від цього контексту (наприклад, IP-адреса віддаленого клієнта та автентифікований ім’я користувача, у наведеному вище прикладі). За таких обставин цілком імовірно, що спеціалізовані Formatters будуть використовуватися з певними Handlers.

Змінено в версії 3.2: Додано параметр stack_info.

Змінено в версії 3.5: Параметр exc_info тепер може приймати винятки.

Змінено в версії 3.8: Додано параметр stacklevel.

info(msg, *args, **kwargs)

Записує повідомлення з рівнем INFO у цьому реєстраторі. Аргументи інтерпретуються як для debug().

warning(msg, *args, **kwargs)

Записує повідомлення з рівнем WARNING до цього реєстратора. Аргументи інтерпретуються як для debug().

Примітка

Існує застарілий метод warn, який функціонально ідентичний warning. Оскільки попередження є застарілим, будь ласка, не використовуйте його - використовуйте замість нього попередження.

error(msg, *args, **kwargs)

Записує повідомлення з рівнем ERROR у цьому реєстраторі. Аргументи інтерпретуються як для debug().

critical(msg, *args, **kwargs)

Записує повідомлення з рівнем CRITICAL до цього реєстратора. Аргументи інтерпретуються як для debug().

log(level, msg, *args, **kwargs)

Записує повідомлення з цілочисельним рівнем level у цьому реєстраторі. Інші аргументи інтерпретуються як для debug().

exception(msg, *args, **kwargs)

Реєструє повідомлення з рівнем ERROR у цьому реєстраторі. Аргументи інтерпретуються як для debug(). Інформація про винятки додається до повідомлення журналу. Цей метод слід викликати лише з обробника винятків.

addFilter(filter)

Додає вказаний фільтр filter до цього реєстратора.

removeFilter(filter)

Видаляє вказаний фільтр filter з цього реєстратора.

filter(record)

Застосуйте фільтри цього реєстратора до запису та поверніть True, якщо запис потрібно обробити. Фільтри перевіряються по черзі, поки один із них не поверне хибне значення. Якщо жоден із них не повертає хибне значення, запис буде оброблено (передано обробникам). Якщо повертається хибне значення, подальша обробка запису не відбувається.

addHandler(hdlr)

Додає вказаний обробник hdlr до цього реєстратора.

removeHandler(hdlr)

Видаляє вказаний обробник hdlr із цього реєстратора.

findCaller(stack_info=False, stacklevel=1)

Знаходить назву вихідного файлу абонента та номер рядка. Повертає назву файлу, номер рядка, назву функції та інформацію про стек у вигляді 4-елементного кортежу. Інформація про стек повертається як None, якщо stack_info не має значення True.

Параметр stacklevel передається з коду, який викликає debug() та інші API. Якщо більше 1, надлишок використовується для пропуску кадрів стека перед визначенням значень, які потрібно повернути. Як правило, це буде корисно під час виклику API реєстрації з допоміжного коду/обгортки, щоб інформація в журналі подій стосувалася не допоміжного/оболонкового коду, а коду, який його викликає.

handle(record)

Обробляє запис, передаючи його всім обробникам, пов’язаним із цим реєстратором та його предками (поки не буде знайдено хибне значення propagate). Цей метод використовується для невибраних записів, отриманих із сокета, а також тих, що створюються локально. Фільтрування на рівні реєстратора застосовується за допомогою filter().

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

Це фабричний метод, який можна замінити в підкласах для створення спеціалізованих екземплярів LogRecord.

hasHandlers()

Перевіряє, чи цей реєстратор має налаштовані обробники. Це робиться шляхом пошуку обробників у цьому реєстраторі та його батьків в ієрархії реєстратора. Повертає True, якщо обробник знайдено, інакше False. Метод припиняє пошук в ієрархії щоразу, коли знайдено реєстратор з атрибутом „propagate“, встановленим на false - це буде останній реєстратор, який перевіряється на наявність обробників.

Нове в версії 3.2.

Змінено в версії 3.7: Лісоруби тепер можна маринувати та не пикувати.

Рівні реєстрації

Числові значення рівнів журналювання наведено в наступній таблиці. Це насамперед цікаво, якщо ви бажаєте визначити власні рівні та потребуєте, щоб вони мали певні значення відносно попередньо визначених рівнів. Якщо ви визначаєте рівень з тим самим числовим значенням, він перезаписує попередньо визначене значення; попередньо визначене ім’я втрачено.

Рівень	Числове значення
CRITICAL	50
ERROR	40
WARNING	30
INFO	20
DEBUG	10
NOTSET	0

Об’єкти обробки

Handlers have the following attributes and methods. Note that Handler is never instantiated directly; this class acts as a base for more useful subclasses. However, the __init__() method in subclasses needs to call Handler.__init__().

class logging.Handler

__init__(level=NOTSET)

Ініціалізує екземпляр Handler, встановлюючи його рівень, встановлюючи список фільтрів у порожній список і створюючи блокування (за допомогою createLock()) для серіалізації доступу до механізму введення-виведення.

createLock()

Ініціалізує блокування потоку, який можна використовувати для серіалізації доступу до основної функції введення-виведення, яка може бути небезпечною для потоків.

acquire()

Отримує блокування потоку, створене за допомогою createLock().

release()

Звільняє блокування потоку, отримане за допомогою acquire().

setLevel(level)

Встановлює порогове значення для цього обробника на рівень. Повідомлення журналу, менш суворі, ніж рівень, ігноруватимуться. Коли обробник створюється, рівень встановлюється на NOTSET (що спричиняє обробку всіх повідомлень).

Перегляньте Рівні реєстрації список рівнів.

Змінено в версії 3.2: Параметр level тепер приймає рядкове представлення рівня, наприклад «INFO», як альтернативу цілим константам, таким як INFO.

setFormatter(fmt)

Встановлює Formatter для цього обробника на fmt.

addFilter(filter)

Додає вказаний фільтр filter до цього обробника.

removeFilter(filter)

Видаляє вказаний фільтр filter з цього обробника.

filter(record)

Застосуйте фільтри цього обробника до запису та поверніть True, якщо запис потрібно обробити. Фільтри перевіряються по черзі, доки один із них не поверне хибне значення. Якщо жоден із них не повертає хибне значення, запис буде видано. Якщо повертається хибне значення, обробник не видасть запис.

flush()

Переконайтеся, що всі вихідні дані журналу скинуто. Ця версія нічого не робить і призначена для реалізації підкласами.

close()

Приберіть усі ресурси, які використовує обробник. Ця версія не виводить, але видаляє обробник із внутрішнього списку обробників, який закривається під час виклику shutdown(). Підкласи повинні гарантувати, що це викликається з перевизначених методів close().

handle(record)

Умовно створює вказаний запис журналу залежно від фільтрів, які могли бути додані до обробника. Обгортає фактичний випуск запису з отриманням/вивільненням блокування потоку вводу-виводу.

handleError(record)

This method should be called from handlers when an exception is encountered during an emit() call. If the module-level attribute raiseExceptions is False, exceptions get silently ignored. This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors. You could, however, replace this with a custom handler if you wish. The specified record is the one which was being processed when the exception occurred. (The default value of raiseExceptions is True, as that is more useful during development).

format(record)

Виконайте форматування для запису - якщо встановлено форматувальник, використовуйте його. В іншому випадку використовуйте стандартний формататор для модуля.

emit(record)

Зробіть усе можливе, щоб фактично зареєструвати вказаний запис журналу. Ця версія призначена для реалізації підкласами, тому викликає NotImplementedError.

Перелік стандартних обробників див. logging.handlers.

Об’єкти форматування

Formatter objects have the following attributes and methods. They are responsible for converting a LogRecord to (usually) a string which can be interpreted by either a human or an external system. The base Formatter allows a formatting string to be specified. If none is supplied, the default value of '%(message)s' is used, which just includes the message in the logging call. To have additional items of information in the formatted output (such as a timestamp), keep reading.

A Formatter can be initialized with a format string which makes use of knowledge of the LogRecord attributes - such as the default value mentioned above making use of the fact that the user’s message and arguments are pre-formatted into a LogRecord’s message attribute. This format string contains standard Python %-style mapping keys. See section Форматування рядків у стилі printf for more information on string formatting.

The useful mapping keys in a LogRecord are given in the section on Атрибути LogRecord.

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True)

Returns a new instance of the Formatter class. The instance is initialized with a format string for the message as a whole, as well as a format string for the date/time portion of a message. If no fmt is specified, '%(message)s' is used. If no datefmt is specified, a format is used which is described in the formatTime() documentation.

The style parameter can be one of „%“, „{“ or „$“ and determines how the format string will be merged with its data: using one of %-formatting, str.format() or string.Template. This only applies to the format string fmt (e.g. '%(message)s' or {message}), not to the actual log messages passed to Logger.debug etc; see Використання певних стилів форматування у вашій програмі for more information on using {- and $-formatting for log messages.

Змінено в версії 3.2: The style parameter was added.

Змінено в версії 3.8: The validate parameter was added. Incorrect or mismatched style and fmt will raise a ValueError. For example: logging.Formatter('%(asctime)s - %(message)s', style='{').

format(record)

The record’s attribute dictionary is used as the operand to a string formatting operation. Returns the resulting string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using msg % args. If the formatting string contains '(asctime)', formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message. Note that the formatted exception information is cached in attribute exc_text. This is useful because the exception information can be pickled and sent across the wire, but you should be careful if you have more than one Formatter subclass which customizes the formatting of exception information. In this case, you will have to clear the cached value after a formatter has done its formatting, so that the next formatter to handle the event doesn’t use the cached value but recalculates it afresh.

Якщо інформація про стек доступна, вона додається після інформації про винятки, використовуючи formatStack() для її перетворення, якщо необхідно.

formatTime(record, datefmt=None)

Цей метод має викликатися з format() програмою форматування, яка бажає використати відформатований час. Цей метод можна замінити у форматах для забезпечення будь-якої конкретної вимоги, але основна поведінка така: якщо вказано datefmt (рядок), він використовується з time.strftime() для форматування часу створення запису. В іншому випадку використовується формат «%Y-%m-%d %H:%M:%S,uuu», де частина uuu є значенням у мілісекундах, а інші літери відповідають time.strftime() документація. Прикладом часу в цьому форматі є 2003-01-23 00:29:50,411. Повертається отриманий рядок.

Ця функція використовує настроювану користувачем функцію для перетворення часу створення в кортеж. За замовчуванням використовується time.localtime(); щоб змінити це для конкретного екземпляра форматера, встановіть атрибут converter на функцію з тим самим підписом, що й time.localtime() або time.gmtime(). Щоб змінити його для всіх засобів форматування, наприклад, якщо ви хочете, щоб усі часи журналювання відображалися за GMT, установіть атрибут converter у класі Formatter.

Змінено в версії 3.3: Раніше формат за замовчуванням був жорстко закодований, як у цьому прикладі: 2010-09-06 22:38:15,292, де частина перед комою обробляється рядком формату strptime ('%Y-%m -%d %H:%M:%S''), а частина після коми є значенням у мілісекундах. Оскільки strptime не має заповнювача формату для мілісекунд, значення мілісекунди додається за допомогою іншого рядка формату, '%s,%03d'' — і обидва ці рядки формату були жорстко закодовані в цьому методі. Зі зміною ці рядки визначаються як атрибути рівня класу, які за бажанням можна замінити на рівні екземпляра. Назви атрибутів: default_time_format (для рядка формату strptime) і default_msec_format (для додавання значення в мілісекундах).

Змінено в версії 3.9: default_msec_format може бути None.

formatException(exc_info)

Форматує вказану інформацію про винятки (стандартний кортеж винятків, який повертає sys.exc_info()) як рядок. Ця реалізація за умовчанням просто використовує traceback.print_exception(). Повертається отриманий рядок.

formatStack(stack_info)

Форматує вказану інформацію про стек (рядок, який повертає traceback.print_stack(), але з видаленням останнього нового рядка) як рядок. Ця реалізація за умовчанням лише повертає вхідне значення.

Фільтр об’єктів

Фільтри можуть використовуватися Обробниками і Реєстраторами для більш складної фільтрації, ніж передбачено рівнями. Базовий клас фільтра дозволяє лише події, які знаходяться нижче певної точки в ієрархії реєстратора. Наприклад, фільтр, ініціалізований «A.B», дозволить події, зареєстровані реєстраторами «A.B», «A.B.C», «A.B.C.D», «A.B.D» тощо, але не «A.BB», «B.A.B» тощо. Якщо ініціалізовано порожнім рядком, усі події передаються.

class logging.Filter(name='')

Повертає екземпляр класу Filter. Якщо вказано ім’я, воно називає реєстратор, події якого разом із дочірніми елементами будуть дозволені через фільтр. Якщо ім’я є порожнім рядком, дозволяється кожна подія.

filter(record)

Is the specified record to be logged? Returns zero for no, nonzero for yes. If deemed appropriate, the record may be modified in-place by this method.

Зауважте, що фільтри, приєднані до обробників, звертаються до того, як обробник випустить подію, тоді як фільтри, приєднані до реєстраторів, звертаються до кожного, коли подія реєструється (за допомогою debug(), info() тощо), до відправка події обробникам. Це означає, що події, які були згенеровані нащадками реєстраторів, не будуть відфільтровані налаштуваннями фільтра реєстратора, якщо фільтр також не застосовано до цих нащадків реєстраторів.

Насправді вам не потрібно створювати підклас Filter: ви можете передати будь-який екземпляр, який має метод filter з тією самою семантикою.

Змінено в версії 3.2: Вам не потрібно створювати спеціалізовані класи Filter або використовувати інші класи з методом filter: ви можете використовувати функцію (або інший виклик) як фільтр. Логіка фільтрації перевірить, чи має об’єкт фільтра атрибут filter: якщо він має, він вважається Filter і викликається його метод filter(). В іншому випадку вважається, що він викликається та викликається із записом як єдиним параметром. Повернене значення має відповідати тому, яке повертає filter().

Хоча фільтри використовуються в основному для фільтрації записів на основі більш складних критеріїв, ніж рівні, вони бачать кожен запис, який обробляється обробником або реєстратором, до якого вони підключені: це може бути корисним, якщо ви хочете зробити щось, наприклад, підрахувати, скільки записи були оброблені певним реєстратором чи обробником, або додаванням, зміною чи видаленням атрибутів у LogRecord, що обробляється. Очевидно, змінювати LogRecord потрібно з певною обережністю, але це дозволяє вставляти контекстну інформацію в журнали (див. Використання фільтрів для передачі контекстної інформації).

Об’єкти LogRecord

Екземпляри LogRecord створюються автоматично Logger щоразу, коли щось реєструється, і можуть бути створені вручну за допомогою makeLogRecord() (наприклад, з марінованої події, отриманої по мережі).

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)

Містить всю інформацію, що стосується події, яка реєструється.

The primary information is passed in msg and args, which are combined using msg % args to create the message field of the record.

Параметри

• name – The name of the logger used to log the event represented by this LogRecord. Note that this name will always have this value, even though it may be emitted by a handler attached to a different (ancestor) logger.

• level – The numeric level of the logging event (one of DEBUG, INFO etc.) Note that this is converted to two attributes of the LogRecord: levelno for the numeric value and levelname for the corresponding level name.

• pathname – The full pathname of the source file where the logging call was made.

• lineno – Номер рядка у вихідному файлі, де було здійснено виклик журналювання.

• msg – The event description message, possibly a format string with placeholders for variable data.

• args – Змінні дані, які потрібно об’єднати в аргумент msg, щоб отримати опис події.

• exc_info – An exception tuple with the current exception information, or None if no exception information is available.

• func – Ім’я функції або методу, з якого було викликано журналювання.

• sinfo – Текстовий рядок, що представляє інформацію про стек від основи стека в поточному потоці до виклику журналювання.

getMessage()

Повертає повідомлення для цього екземпляра LogRecord після об’єднання будь-яких наданих користувачем аргументів із повідомленням. Якщо наданий користувачем аргумент повідомлення для виклику журналювання не є рядком, str() викликається для нього, щоб перетворити його на рядок. Це дозволяє використовувати визначені користувачем класи як повідомлення, чий метод __str__ може повертати фактичний рядок формату для використання.

Змінено в версії 3.2: Створення LogRecord було зроблено більш настроюваним шляхом надання фабрики, яка використовується для створення запису. Фабрику можна встановити за допомогою getLogRecordFactory() і setLogRecordFactory() (див. тут підпис фабрики).

Цю функцію можна використовувати для введення ваших власних значень у LogRecord під час створення. Ви можете використовувати наступний шаблон:

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

За допомогою цього шаблону кілька фабрик можуть бути з’єднані в ланцюг, і якщо вони не перезаписують атрибути одна одної або ненавмисно перезаписують стандартні атрибути, перелічені вище, не повинно бути сюрпризів.

Атрибути LogRecord

LogRecord має низку атрибутів, більшість із яких є похідними від параметрів конструктора. (Зауважте, що імена параметрів конструктора LogRecord і атрибутів LogRecord не завжди точно збігаються.) Ці атрибути можна використовувати для об’єднання даних із запису в рядок формату. У наведеній нижче таблиці наведено (в алфавітному порядку) назви атрибутів, їх значення та відповідний заповнювач у рядку формату %-style.

Якщо ви використовуєте {}-formatting (str.format()), ви можете використовувати {attrname} як заповнювач у рядку формату. Якщо ви використовуєте $-форматування (string.Template), використовуйте форму ${attrname}. В обох випадках, звичайно, замініть attrname фактичним ім’ям атрибута, який ви хочете використовувати.

In the case of {}-formatting, you can specify formatting flags by placing them after the attribute name, separated from it with a colon. For example: a placeholder of {msecs:03d} would format a millisecond value of 4 as 004. Refer to the str.format() documentation for full details on the options available to you.

Назва атрибута	Формат	опис
арг	Вам не потрібно форматувати це самостійно.	Кортеж аргументів об’єднано в msg для створення message або dict, значення якого використовуються для злиття (якщо є лише один аргумент, і це словник).
asctime	%(asctime)s	Зрозумілий для людини час створення LogRecord. За замовчуванням це має форму «2003-07-08 16:49:45,896» (числа після коми є частиною часу в мілісекундах).
створений	%(created)f	Time when the LogRecord was created (as returned by time.time()).
exc_info	Вам не потрібно форматувати це самостійно.	Кортеж винятків (à la sys.exc_info) або, якщо винятків не сталося, None.
ім’я файлу	%(filename)s	Частина імені файлу шляху.
ім’я функції	%(funcName)s	Назва функції, яка містить виклик журналювання.
ім’я рівня	%(levelname)s	Рівень реєстрації тексту для повідомлення ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
levelno	%(levelno)s	Числовий рівень журналювання для повідомлення (DEBUG, INFO, WARNING, ERROR, CRITICAL).
lineno	%(lineno)d	Номер вихідного рядка, де було здійснено виклик реєстрації (за наявності).
повідомлення	%(message)s	Зареєстроване повідомлення, обчислене як msg % args. Це встановлюється під час виклику Formatter.format().
модуль	%(module)s	Модуль (частина назви назви файлу).
мс	%(msecs)d	Частина мілісекунд часу, коли було створено LogRecord.
повідомлення	Вам не потрібно форматувати це самостійно.	Рядок формату, переданий у вихідному виклику журналювання. Об’єднано з args для отримання message або довільного об’єкта (див. Використання довільних об’єктів як повідомлень).
назва	%(name)s	Ім’я реєстратора, який використовувався для реєстрації виклику.
шлях	%(pathname)s	Повний шлях до вихідного файлу, до якого було здійснено виклик журналювання (за наявності).
процес	%(process)d	ID процесу (за наявності).
назва процесу	%(processName)s	Назва процесу (якщо є).
relativeCreated	%(relativeCreated)d	Час у мілісекундах, коли було створено LogRecord, відносно часу завантаження модуля журналювання.
stack_info	Вам не потрібно форматувати це самостійно.	Інформація про стек (якщо доступно) від нижньої частини стека в поточному потоці до та включно з кадром стека виклику журналювання, який призвів до створення цього запису.
нитка	%(thread)d	ID потоку (якщо є).
ім’я потоку	%(threadName)s	Назва теми (за наявності).

Змінено в версії 3.1: Додано processName.

Об’єкти LoggerAdapter

Екземпляри LoggerAdapter використовуються для зручної передачі контекстної інформації у виклики журналювання. Для прикладу використання дивіться розділ про додавання контекстної інформації до вихідних даних журналу.

class logging.LoggerAdapter(logger, extra)

Returns an instance of LoggerAdapter initialized with an underlying Logger instance and a dict-like object.

process(msg, kwargs)

Змінює повідомлення та/або ключові аргументи, передані виклику журналювання, щоб вставити контекстну інформацію. Ця реалізація приймає об’єкт, переданий як extra до конструктора, і додає його до kwargs за допомогою ключа «extra». Поверненим значенням є кортеж (msg, kwargs), який містить (можливо, змінені) версії переданих аргументів.

На додаток до вищезазначеного, LoggerAdapter підтримує такі методи Logger: debug(), info(), warning(), error(), exception(), critical(), log(), isEnabledFor(), getEffectiveLevel(), setLevel() і hasHandlers(). Ці методи мають ті самі сигнатури, що й їхні аналоги в Logger, тому ви можете використовувати обидва типи екземплярів як взаємозамінні.

Змінено в версії 3.2: Методи isEnabledFor(), getEffectiveLevel(), setLevel() і hasHandlers() додано до LoggerAdapter . Ці методи делегують базовому реєстратору.

Змінено в версії 3.6: Attribute manager and method _log() were added, which delegate to the underlying logger and allow adapters to be nested.

Безпека ниток

Модуль журналювання призначений для потокобезпечної роботи без необхідності виконання будь-якої спеціальної роботи клієнтами. Це досягається за допомогою різьбових замків; існує одне блокування для серіалізації доступу до спільних даних модуля, і кожен обробник також створює блокування для серіалізації доступу до базового введення-виведення.

Якщо ви впроваджуєте асинхронні обробники сигналів за допомогою модуля signal, можливо, ви не зможете використовувати журналювання в таких обробниках. Це пов’язано з тим, що реалізації блокувань у модулі threading не завжди можна повторно входити, і тому їх не можна викликати з таких обробників сигналів.

Функції рівня модуля

На додаток до класів, описаних вище, існує ряд функцій рівня модуля.

logging.getLogger(name=None)

Return a logger with the specified name or, if name is None, return a logger which is the root logger of the hierarchy. If specified, the name is typically a dot-separated hierarchical name like „a“, „a.b“ or „a.b.c.d“. Choice of these names is entirely up to the developer who is using logging.

Усі виклики цієї функції з заданим іменем повертають той самий екземпляр журналу. Це означає, що екземпляри реєстратора ніколи не потрібно передавати між різними частинами програми.

logging.getLoggerClass()

Повертає або стандартний клас Logger, або останній клас, переданий setLoggerClass(). Цю функцію можна викликати з нового визначення класу, щоб гарантувати, що встановлення налаштованого класу Logger не скасує налаштування, уже застосовані іншим кодом. Наприклад:

class MyLogger(logging.getLoggerClass()):
    # ... override behaviour here

logging.getLogRecordFactory()

Повертає виклик, який використовується для створення LogRecord.

Нове в версії 3.2: Цю функцію було надано разом із setLogRecordFactory(), щоб дозволити розробникам більше контролювати те, як створюється LogRecord, що представляє подію журналювання.

Перегляньте setLogRecordFactory() для отримання додаткової інформації про те, як називається фабрика.

logging.debug(msg, *args, **kwargs)

Logs a message with level DEBUG on the root logger. The msg is the message format string, and the args are the arguments which are merged into msg using the string formatting operator. (Note that this means that you can use keywords in the format string, together with a single dictionary argument.)

There are three keyword arguments in kwargs which are inspected: exc_info which, if it does not evaluate as false, causes exception information to be added to the logging message. If an exception tuple (in the format returned by sys.exc_info()) or an exception instance is provided, it is used; otherwise, sys.exc_info() is called to get the exception information.

Другим необов’язковим ключовим аргументом є stack_info, який за умовчанням має значення False. Якщо значення true, інформація про стек додається до повідомлення журналу, включаючи фактичний виклик журналу. Зауважте, що це інша інформація про стек, яка відображається за допомогою exc_info: перша – це кадри стеку від нижньої частини стеку до виклику журналювання в поточному потоці, тоді як остання – це інформація про кадри стеку, які були переглянуті. unwind, після винятку, під час пошуку обробників винятків.

Ви можете вказати stack_info незалежно від exc_info, наприклад. щоб просто показати, як ви дійшли до певної точки у своєму коді, навіть якщо винятків не було викликано. Фрейми стека друкуються після рядка заголовка, який говорить:

Stack (most recent call last):

Це імітує Traceback (останній останній виклик):, який використовується під час відображення кадрів винятків.

The third optional keyword argument is extra which can be used to pass a dictionary which is used to populate the __dict__ of the LogRecord created for the logging event with user-defined attributes. These custom attributes can then be used as you like. For example, they could be incorporated into logged messages. For example:

FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logging.warning('Protocol problem: %s', 'connection reset', extra=d)

would print something like:

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

The keys in the dictionary passed in extra should not clash with the keys used by the logging system. (See the Formatter documentation for more information on which keys are used by the logging system.)

If you choose to use these attributes in logged messages, you need to exercise some care. In the above example, for instance, the Formatter has been set up with a format string which expects „clientip“ and „user“ in the attribute dictionary of the LogRecord. If these are missing, the message will not be logged because a string formatting exception will occur. So in this case, you always need to pass the extra dictionary with these keys.

Хоча це може дратувати, ця функція призначена для використання в особливих умовах, наприклад, на багатопоточних серверах, де той самий код виконується в багатьох контекстах, і цікаві умови, які виникають, залежать від цього контексту (наприклад, IP-адреса віддаленого клієнта та автентифікований ім’я користувача, у наведеному вище прикладі). За таких обставин цілком імовірно, що спеціалізовані Formatters будуть використовуватися з певними Handlers.

Змінено в версії 3.2: Додано параметр stack_info.

logging.info(msg, *args, **kwargs)

Logs a message with level INFO on the root logger. The arguments are interpreted as for debug().

logging.warning(msg, *args, **kwargs)

Logs a message with level WARNING on the root logger. The arguments are interpreted as for debug().

Примітка

Існує застаріла функція warn, яка функціонально ідентична warning. Оскільки попередження застаріло, будь ласка, не використовуйте його - використовуйте замість нього попередження.

logging.error(msg, *args, **kwargs)

Logs a message with level ERROR on the root logger. The arguments are interpreted as for debug().

logging.critical(msg, *args, **kwargs)

Logs a message with level CRITICAL on the root logger. The arguments are interpreted as for debug().

logging.exception(msg, *args, **kwargs)

Logs a message with level ERROR on the root logger. The arguments are interpreted as for debug(). Exception info is added to the logging message. This function should only be called from an exception handler.

logging.log(level, msg, *args, **kwargs)

Logs a message with level level on the root logger. The other arguments are interpreted as for debug().

logging.disable(level=CRITICAL)

Забезпечує переважний рівень рівень для всіх реєстраторів, який має перевагу над власним рівнем реєстратора. Ця функція може бути корисною, коли виникає потреба тимчасово зменшити вивід журналювання в усій програмі. Його ефект полягає в тому, щоб вимкнути всі виклики журналювання рівня серйозності рівня і нижче, так що якщо ви викликаєте його зі значенням INFO, тоді всі події INFO та DEBUG будуть відхилені, тоді як події серйозності WARNING і вище будуть оброблені відповідно до ефективний рівень реєстратора. Якщо викликається logging.disable(logging.NOTSET), це фактично видаляє цей переважний рівень, так що вихід журналу знову залежить від ефективних рівнів окремих реєстраторів.

Зауважте, що якщо ви визначили будь-який спеціальний рівень журналювання, вищий за КРИТИЧНИЙ (це не рекомендовано), ви не зможете покладатися на значення за замовчуванням для параметра level, але вам доведеться явно вказати відповідне значення.

Змінено в версії 3.7: Параметр level за замовчуванням мав рівень КРИТИЧНИЙ. Перегляньте bpo-28524, щоб дізнатися більше про цю зміну.

logging.addLevelName(level, levelName)

Пов’язує рівень level із текстом levelName у внутрішньому словнику, який використовується для відображення числових рівнів у текстовому представленні, наприклад, коли Formatter форматує повідомлення. Цю функцію також можна використовувати для визначення власних рівнів. Єдині обмеження полягають у тому, що всі використовувані рівні мають бути зареєстровані за допомогою цієї функції, рівні мають бути додатними цілими числами, і вони мають збільшуватися в порядку зростання серйозності.

Примітка

Якщо ви плануєте визначити власні рівні, перегляньте розділ про Спеціальні рівні.

logging.getLevelName(level)

Повертає текстове або числове представлення рівня реєстрації level.

Якщо level є одним із попередньо визначених рівнів CRITICAL, ERROR, WARNING, INFO або DEBUG, тоді ви отримаєте відповідний рядок . Якщо ви пов’язали рівні з іменами за допомогою addLevelName(), тоді повертається ім’я, яке ви пов’язали з рівнем. Якщо передано числове значення, що відповідає одному з визначених рівнів, повертається відповідне представлення рядка.

Параметр level також приймає рядкове представлення рівня, наприклад «INFO». У таких випадках ця функція повертає відповідне числове значення рівня.

Якщо відповідного числового або рядкового значення не передано, повертається рядок «Рівень %s» % рівня.

Примітка

Рівні є внутрішніми цілими числами (оскільки їх потрібно порівнювати в логіці журналювання). Ця функція використовується для перетворення між цілочисельним рівнем і назвою рівня, що відображається у форматованому виведенні журналу за допомогою специфікатора формату %(levelname)s (див. Атрибути LogRecord), і навпаки.

Змінено в версії 3.4: У версіях Python, раніших за 3.4, ця функція також могла передаватися на текстовий рівень і повертала б відповідне числове значення рівня. Ця незадокументована поведінка вважалася помилкою та була видалена в Python 3.4, але відновлена в 3.4.2 через збереження зворотної сумісності.

logging.makeLogRecord(attrdict)

Створює та повертає новий екземпляр LogRecord, атрибути якого визначено attrdict. Ця функція корисна для того, щоб взяти вибраний словник атрибутів LogRecord, надісланий через сокет, і відтворити його як екземпляр LogRecord на кінці прийому.

logging.basicConfig(**kwargs)

Виконує базову конфігурацію для системи журналювання, створюючи StreamHandler із стандартним Formatter і додаючи його до кореневого реєстратора. Функції debug(), info(), warning(), error() і critical() викличуть basicConfig() автоматично, якщо не визначено обробників для кореневого реєстратора.

Ця функція нічого не робить, якщо кореневий реєстратор уже має налаштовані обробники, якщо для ключового аргументу force не встановлено значення True.

Примітка

Цю функцію слід викликати з основного потоку перед запуском інших потоків. У версіях Python до 2.7.1 і 3.2, якщо ця функція викликається з кількох потоків, можливо (у рідкісних випадках), що обробник буде додано до кореневого журналу більше одного разу, що призведе до неочікуваних результатів, таких як повідомлення дублюється в журналі.

Підтримуються наступні аргументи ключових слів.

Формат	опис
назва файлу	Specifies that a FileHandler be created, using the specified filename, rather than a StreamHandler.
файловий режим	Якщо вказано ім’я файлу, відкрийте файл у цьому режимі. За замовчуванням 'a''.
формат	Використовуйте вказаний рядок формату для обробника. За замовчуванням атрибути levelname, name і message, розділені двокрапками.
datefmt	Використовуйте вказаний формат дати/часу, прийнятний time.strftime().
стиль	Якщо вказано format, використовуйте цей стиль для рядка формату. Один із '%', '{' або '$' для printf-style, str.format() або string .Template відповідно. За замовчуванням '%''.
рівень	Встановіть рівень кореневого реєстратора на вказаний level.
потік	Use the specified stream to initialize the StreamHandler. Note that this argument is incompatible with filename - if both are present, a ValueError is raised.
обробники	Якщо вказано, це має бути ітерація вже створених обробників для додавання до кореневого реєстратора. Усім обробникам, які ще не мають встановленого форматера, буде призначено стандартний форматер, створений у цій функції. Зауважте, що цей аргумент несумісний з filename або stream - якщо обидва присутні, виникає помилка ValueError.
сила	Якщо цей аргумент ключового слова вказано як true, будь-які існуючі обробники, приєднані до кореневого реєстратора, видаляються та закриваються перед виконанням конфігурації, як зазначено іншими аргументами.
кодування	If this keyword argument is specified along with filename, its value is used when the FileHandler is created, and thus used when opening the output file.
помилки	If this keyword argument is specified along with filename, its value is used when the FileHandler is created, and thus used when opening the output file. If not specified, the value „backslashreplace“ is used. Note that if None is specified, it will be passed as such to func:open, which means that it will be treated the same as passing „errors“.

Змінено в версії 3.2: Додано аргумент style.

Змінено в версії 3.3: Додано аргумент обробники. Було додано додаткові перевірки для виявлення ситуацій, коли вказано несумісні аргументи (наприклад, обробники разом із потоком або ім’ям файлу, або потік разом із ім’ям файлу).

Змінено в версії 3.8: Додано аргумент force.

Змінено в версії 3.9: Додано аргументи encoding і errors.

logging.shutdown()

Повідомляє системі журналювання виконати впорядковане завершення роботи шляхом очищення та закриття всіх обробників. Це слід викликати під час виходу з програми, і після цього виклику не слід використовувати систему журналювання.

Коли модуль журналювання імпортовано, він реєструє цю функцію як обробник виходу (див. atexit), тому зазвичай немає потреби робити це вручну.

logging.setLoggerClass(klass)

Tells the logging system to use the class klass when instantiating a logger. The class should define __init__() such that only a name argument is required, and the __init__() should call Logger.__init__(). This function is typically called before any loggers are instantiated by applications which need to use custom logger behavior. After this call, as at any other time, do not instantiate loggers directly using the subclass: continue to use the logging.getLogger() API to get your loggers.

logging.setLogRecordFactory(factory)

Встановіть виклик, який використовується для створення LogRecord.

Параметри

factory – Фабричний виклик, який буде використано для створення екземпляра запису журналу.

Нове в версії 3.2: Цю функцію було надано разом із getLogRecordFactory(), щоб дозволити розробникам більше контролювати те, як створюється LogRecord, що представляє подію журналювання.

Завод має такий підпис:

factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

назва

Ім’я реєстратора.

рівень

Рівень журналювання (числовий).

фн

Повний шлях до файлу, у якому було здійснено виклик журналювання.

льно

Номер рядка у файлі, де було здійснено виклик журналювання.

повідомлення

Повідомлення реєстрації.

арг

Аргументи для повідомлення журналу.

exc_info

Кортеж винятків або None.

функц

Ім’я функції або методу, які викликали журналювання.

sinfo

Зворотне трасування стека, наприклад, надається traceback.print_stack(), показуючи ієрархію викликів.

kwargs

Додаткові аргументи ключових слів.

Атрибути рівня модуля

logging.lastResort

Через цей атрибут доступний «обробник останньої надії». Це StreamHandler, який записує в sys.stderr з рівнем WARNING і використовується для обробки подій журналювання за відсутності будь-якої конфігурації журналювання. Кінцевим результатом є просто друк повідомлення в sys.stderr. Це замінює попереднє повідомлення про помилку про те, що «не вдалося знайти обробників для реєстратора XYZ». Якщо з якоїсь причини вам потрібна попередня поведінка, для lastResort можна встановити значення None.

Нове в версії 3.2.

Інтеграція з модулем попереджень

Функцію captureWarnings() можна використовувати для інтеграції logging з модулем warnings.

logging.captureWarnings(capture)

Ця функція використовується для ввімкнення та вимкнення захоплення попереджень під час входу.

Якщо capture має значення True, попередження, видані модулем warnings, будуть перенаправлені до системи журналювання. Зокрема, попередження буде відформатовано за допомогою warnings.formatwarning(), а результуючий рядок буде зареєстровано в журналі під назвою 'py.warnings з серйозністю WARNING.

Якщо capture має значення False, перенаправлення попереджень до системи журналювання припиниться, і попередження будуть перенаправлені до початкових місць призначення (тобто тих, які діяли до виклику captureWarnings(True)).

Дивись також

Модуль logging.config

API конфігурації для модуля журналювання.

Модуль logging.handlers

Корисні обробники, включені в модуль журналювання.

PEP 282 - Система реєстрації

Пропозиція, яка описує цю функцію для включення в стандартну бібліотеку Python.

Оригінальний пакет журналювання Python

Це оригінальне джерело пакета logging. Версія пакета, доступна на цьому сайті, підходить для використання з Python 1.5.2, 2.1.x і 2.2.x, які не містять пакет logging у стандартній бібліотеці.