logging.handlers — Logging handlers

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

Important

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

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

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

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

---

Наступні корисні обробники надаються в пакеті. Зауважте, що три обробники (StreamHandler, FileHandler і NullHandler) насправді визначені в самому модулі logging, але були задокументовані тут разом із інші обробники.

StreamHandler

Клас StreamHandler, розташований у базовому пакеті logging, надсилає вихідні дані журналу до таких потоків, як sys.stdout, sys.stderr або будь-якого файлоподібного об’єкта (або, точніше, , будь-який об’єкт, який підтримує методи write() і flush()).

class logging.StreamHandler(stream=None)

Повертає новий екземпляр класу StreamHandler. Якщо вказано потік, примірник використовуватиме його для журналювання виводу; інакше буде використано sys.stderr.

emit(record)

Якщо вказано засіб форматування, він використовується для форматування запису. Потім запис записується в потік, а потім terminator. Якщо присутня інформація про винятки, вона форматується за допомогою traceback.print_exception() і додається до потоку.

flush()

Очищає потік, викликаючи його метод flush(). Зауважте, що метод close() успадковано від Handler і тому не виводить, тому іноді може знадобитися явний виклик flush().

setStream(stream)

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

Параметри:

stream – Потік, який повинен використовувати обробник.

Повертає:

the old stream, if the stream was changed, or None if it wasn’t.

Added in version 3.7.

terminator

Рядок, який використовується як термінатор під час запису форматованого запису в потік. Значення за замовчуванням - '\n'.

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

У попередніх версіях термінатор був жорстко закодований як '\n'.

Added in version 3.2.

FileHandler

Клас FileHandler, розташований у базовому пакеті logging, надсилає вихідні дані журналу у файл диска. Він успадковує функцію виведення від StreamHandler.

class logging.FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the FileHandler class. The specified file is opened and used as the stream for logging. If mode is not specified, 'a' is used. If encoding is not None, it is used to open the file with that encoding. If delay is true, then file opening is deferred until the first call to emit(). By default, the file grows indefinitely. If errors is specified, it’s used to determine how encoding errors are handled.

Змінено в версії 3.6: Окрім рядкових значень, об’єкти Path також приймаються для аргументу filename.

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

close()

Закриває файл.

emit(record)

Виводить запис у файл.

Зауважте, що якщо файл було закрито через завершення журналювання під час виходу та режим файлу «w», запис не буде видано (див. bpo-42378).

NullHandler

Added in version 3.1.

Клас NullHandler, розташований у базовому пакеті logging, не виконує жодного форматування чи виведення. По суті, це обробник «no-op» для використання розробниками бібліотек.

class logging.NullHandler

Повертає новий екземпляр класу NullHandler.

emit(record)

Цей метод нічого не робить.

handle(record)

Цей метод нічого не робить.

createLock()

Цей метод повертає None для блокування, оскільки немає основного вводу-виводу, доступ до якого потрібно серіалізувати.

Перегляньте Налаштування журналювання для бібліотеки, щоб дізнатися більше про використання NullHandler.

WatchedFileHandler

Клас WatchedFileHandler, розташований у модулі logging.handlers, є FileHandler, який стежить за файлом, до якого він реєструється. Якщо файл змінюється, він закривається та знову відкривається з використанням імені файлу.

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

Цей обробник не підходить для використання під Windows, оскільки під Windows відкриті файли журналу не можна переміщувати або перейменовувати - журналювання відкриває файли з ексклюзивними блокуваннями - і тому немає потреби в такому обробнику. Крім того, ST_INO не підтримується в Windows; stat() завжди повертає нуль для цього значення.

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the WatchedFileHandler class. The specified file is opened and used as the stream for logging. If mode is not specified, 'a' is used. If encoding is not None, it is used to open the file with that encoding. If delay is true, then file opening is deferred until the first call to emit(). By default, the file grows indefinitely. If errors is provided, it determines how encoding errors are handled.

Змінено в версії 3.6: Окрім рядкових значень, об’єкти Path також приймаються для аргументу filename.

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

reopenIfNeeded()

Перевіряє, чи не змінився файл. Якщо так, наявний потік очищається та закривається, а файл відкривається знову, як правило, перед виведенням запису у файл.

Added in version 3.6.

emit(record)

Виводить запис у файл, але спочатку викликає reopenIfNeeded(), щоб повторно відкрити файл, якщо він змінився.

BaseRotatingHandler

Клас BaseRotatingHandler, розташований у модулі logging.handlers, є базовим класом для обертових обробників файлів, RotatingFileHandler і TimedRotatingFileHandler. Вам не потрібно створювати екземпляр цього класу, але він має атрибути та методи, які вам, можливо, доведеться змінити.

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)

Параметри такі ж, як і для FileHandler. Атрибути:

namer

Якщо для цього атрибута встановлено значення callable, метод rotation_filename() делегує цей виклик. Параметри, що передаються викликаному, є тими, що передаються до rotation_filename().

Примітка

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

Варто також зазначити, що під час використання іменника слід бути обережним, щоб зберегти певні атрибути в імені файлу, які використовуються під час ротації. Наприклад, RotatingFileHandler очікує мати набір файлів журналу, імена яких містять послідовні цілі числа, щоб ротація працювала належним чином, а TimedRotatingFileHandler видаляє старі файли журналу (на основі backupCount параметр, переданий ініціалізатору обробника), визначаючи найстаріші файли для видалення. Щоб це сталося, назви файлів мають бути сортованими за датою/часом у назві файлу, і іменувальник має поважати це. (Якщо потрібен іменник, який не відповідає цій схемі, його потрібно буде використовувати в підкласі TimedRotatingFileHandler, який замінює метод getFilesToDelete(), щоб відповідати спеціальному іменуванню схема.)

Added in version 3.3.

rotator

Якщо цей атрибут встановлено на callable, метод rotate() делегує цей callable. Параметри, що передаються викликаному, є тими, що передаються в rotate().

Added in version 3.3.

rotation_filename(default_name)

Змінити назву файлу журналу під час ротації.

Це надається для того, щоб можна було надати власне ім’я файлу.

Реалізація за замовчуванням викликає атрибут „namer“ обробника, якщо його можна викликати, передаючи йому ім’я за замовчуванням. Якщо атрибут не можна викликати (за замовчуванням None), ім’я повертається без змін.

Параметри:

default_name – Назва за замовчуванням для файлу журналу.

Added in version 3.3.

rotate(source, dest)

Під час обертання обертати поточний журнал.

Реалізація за замовчуванням викликає атрибут „rotator“ обробника, якщо його можна викликати, передаючи йому аргументи джерела та призначення. Якщо атрибут не можна викликати (за замовчуванням None), джерело просто перейменовується на призначення.

Параметри:

• source – Ім’я вихідного файлу. Зазвичай це базова назва файлу, напр. „test.log“.

• dest – Ім’я цільового файлу. Зазвичай це те, до чого обертається джерело, напр. „test.log.1“.

Added in version 3.3.

Причина, чому ці атрибути існують, полягає в тому, щоб позбавити вас необхідності створювати підкласи – ви можете використовувати ті самі виклики для екземплярів RotatingFileHandler і TimedRotatingFileHandler. Якщо виклик іменника або ротатора викликає виняток, це буде оброблено так само, як і будь-який інший виняток під час виклику emit(), тобто через метод handleError() обробника.

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

Для прикладу перегляньте Використання ротатора та іменника для налаштування обробки ротації журналу.

RotatingFileHandler

Клас RotatingFileHandler, розташований у модулі logging.handlers, підтримує ротацію файлів журналу диска.

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

Повертає новий екземпляр класу RotatingFileHandler. Зазначений файл відкривається та використовується як потік для реєстрації. Якщо mode не вказано, використовується 'a'. Якщо кодування не None, воно використовується для відкриття файлу з таким кодуванням. Якщо delay має значення true, то відкриття файлу відкладено до першого виклику emit(). За замовчуванням файл збільшується необмежено довго. Якщо вказано errors, це визначає спосіб обробки помилок кодування.

Ви можете використовувати значення maxBytes і backupCount, щоб дозволити файлу rollover попередньо визначеного розміру. Коли розмір майже буде перевищено, файл закривається, а новий файл мовчки відкривається для виведення. Перехід відбувається щоразу, коли довжина поточного файлу журналу становить майже maxBytes; але якщо будь-яке з maxBytes або backupCount дорівнює нулю, перехід ніколи не відбувається, тому зазвичай потрібно встановити backupCount принаймні на 1 і мати ненульовий maxBytes. Якщо backupCount не дорівнює нулю, система збереже старі файли журналу, додавши до назви файлу розширення «.1», «.2» тощо. Наприклад, з backupCount 5 і базовою назвою файлу app.log, ви отримаєте app.log, app.log.1, app.log.2, до app.log.5. Файл, у який записується, завжди app.log. Коли цей файл заповнюється, він закривається та перейменовується на app.log.1, а якщо файли app.log.1, app.log.2 тощо. існують, тоді вони перейменовуються відповідно на app.log.2, app.log.3 тощо.

Змінено в версії 3.6: Окрім рядкових значень, об’єкти Path також приймаються для аргументу filename.

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

doRollover()

Робить перекидання, як описано вище.

emit(record)

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

shouldRollover(record)

See if the supplied record would cause the file to exceed the configured size limit.

TimedRotatingFileHandler

Клас TimedRotatingFileHandler, розташований у модулі logging.handlers, підтримує ротацію файлів журналу диска через певні часові інтервали.

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

Повертає новий екземпляр класу TimedRotatingFileHandler. Зазначений файл відкривається та використовується як потік для реєстрації. При обертанні він також встановлює суфікс імені файлу. Обертання відбувається на основі добутку when та інтервалу.

Ви можете використовувати when, щоб вказати тип інтервалу. Нижче наведено список можливих значень. Зауважте, що вони не чутливі до регістру.

Значення	Тип інтервалу	Якщо/як використовується atTime
'S'	секунд	Ігнорується
'M''	хвилин	Ігнорується
'H''	години	Ігнорується
'D''	днів	Ігнорується
'W0'-'W6'	День тижня (0=понеділок)	Використовується для обчислення початкового часу перекидання
"опівніч"	Перехід опівночі, якщо atTime не вказано, інакше в час atTime	Використовується для обчислення початкового часу перекидання

У разі використання ротації на основі днів тижня вкажіть «W0» для понеділка, «W1» для вівторка і так далі до «W6» для неділі. У цьому випадку значення, передане для інтервалу, не використовується.

Система збереже старі файли журналу, додавши розширення до імені файлу. Розширення базуються на даті й часі з використанням формату strftime %Y-%m-%d_%H-%M-%S або його початкової частини, залежно від інтервалу переходу.

Під час першого обчислення часу наступного переходу (під час створення обробника) для обчислення часу наступного повороту використовується час останньої зміни наявного файлу журналу або поточний час.

Якщо аргумент utc має значення true, буде використано час у UTC; інакше використовується місцевий час.

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

Якщо delay має значення true, то відкриття файлу відкладено до першого виклику emit().

Якщо atTime не є None, це має бути екземпляр datetime.time, який визначає час доби, коли відбувається перекидання, для випадків, коли перекидання встановлено на «опівночі» або «на певний день тижня». Зауважте, що в цих випадках значення atTime ефективно використовується для обчислення початкового ролловера, а наступні ролловери обчислюватимуться за допомогою звичайного обчислення інтервалу.

Якщо вказано errors, воно використовується для визначення способу обробки помилок кодування.

Примітка

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

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

Змінено в версії 3.6: Окрім рядкових значень, об’єкти Path також приймаються для аргументу filename.

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

doRollover()

Робить перекидання, як описано вище.

emit(record)

Виводить запис у файл, обслуговуючи ролловер, як описано вище.

getFilesToDelete()

Returns a list of filenames which should be deleted as part of rollover. These

shouldRollover(record)

See if enough time has passed for a rollover to occur and if it has, compute the next rollover time.

SocketHandler

Клас SocketHandler, розташований у модулі logging.handlers, надсилає вихідні дані журналу в мережевий сокет. Базовий клас використовує сокет TCP.

class logging.handlers.SocketHandler(host, port)

Повертає новий екземпляр класу SocketHandler, призначений для зв’язку з віддаленою машиною, адресу якої вказують host і port.

Змінено в версії 3.4: Якщо port вказано як None, сокет домену Unix створюється за допомогою значення в host - інакше створюється сокет TCP.

close()

Закриває розетку.

emit()

Вибирає словник атрибутів запису та записує його в сокет у двійковому форматі. Якщо є помилка з сокетом, мовчки скидає пакет. Якщо з’єднання було втрачено, відновлює з’єднання. Щоб видалити запис на приймальному кінці в LogRecord, скористайтеся makeLogRecord() функцією.

handleError()

Обробляє помилку, яка сталася під час emit(). Найімовірніша причина – втрата зв’язку. Закриває сокет, щоб ми могли повторити наступну подію.

makeSocket()

Це фабричний метод, який дозволяє підкласам визначати точний тип сокета, який вони хочуть. Стандартна реалізація створює сокет TCP (socket.SOCK_STREAM).

makePickle(record)

Вибирає словник атрибутів запису в двійковому форматі з префіксом довжини та повертає його готовим для передачі через сокет. Подробиці цієї операції еквівалентні:

data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
return datalen + data

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

send(packet)

Надішліть маринований байтовий рядок пакет до сокета. Формат надісланого байтового рядка відповідає документації для makePickle().

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

createSocket()

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

Ця поведінка контролюється такими атрибутами обробника:

• retryStart (початкова затримка, за замовчуванням 1,0 секунди).

• retryFactor (множник, за умовчанням 2,0).

• retryMax (максимальна затримка, за замовчуванням 30,0 секунд).

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

DatagramHandler

Клас DatagramHandler, розташований у модулі logging.handlers, успадковує SocketHandler для підтримки надсилання повідомлень журналу через сокети UDP.

class logging.handlers.DatagramHandler(host, port)

Повертає новий екземпляр класу DatagramHandler, призначений для зв’язку з віддаленою машиною, адресу якої вказують host і port.

Примітка

As UDP is not a streaming protocol, there is no persistent connection between an instance of this handler and host. For this reason, when using a network socket, a DNS lookup might have to be made each time an event is logged, which can introduce some latency into the system. If this affects you, you can do a lookup yourself and initialize this handler using the looked-up IP address rather than the hostname.

Змінено в версії 3.4: Якщо port вказано як None, сокет домену Unix створюється за допомогою значення в host; інакше створюється сокет UDP.

emit()

Вибирає словник атрибутів запису та записує його в сокет у двійковому форматі. Якщо є помилка з сокетом, мовчки скидає пакет. Щоб видалити запис на приймальному кінці в LogRecord, скористайтеся makeLogRecord() функцією.

makeSocket()

Фабричний метод SocketHandler тут перевизначено для створення сокета UDP (socket.SOCK_DGRAM).

send(s)

Надіслати маринований рядок байтів до сокета. Формат надісланого байтового рядка відповідає документації для SocketHandler.makePickle().

SysLogHandler

Клас SysLogHandler, розташований у модулі logging.handlers, підтримує надсилання повідомлень журналу до віддаленого чи локального системного журналу Unix.

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)

Повертає новий екземпляр класу SysLogHandler, призначений для зв’язку з віддаленою машиною Unix, адреса якої задана адресою у формі кортежу (хост, порт). Якщо адреса не вказана, використовується ('localhost', 514). Адреса використовується для відкриття сокета. Альтернативою наданню кортежу (хост, порт) є надання адреси у вигляді рядка, наприклад „/dev/log“. У цьому випадку для надсилання повідомлення до системного журналу використовується сокет домену Unix. Якщо facility не вказано, LOG_USER використовується. Тип відкритого сокета залежить від аргументу socktype, який за замовчуванням має значення socket.SOCK_DGRAM і таким чином відкриває сокет UDP. Щоб відкрити сокет TCP (для використання з новими демонами syslog, наприклад rsyslog), вкажіть значення socket.SOCK_STREAM.

Зауважте, що якщо ваш сервер не прослуховує UDP-порт 514, SysLogHandler може здатися непрацюючим. У такому випадку перевірте, яку адресу ви повинні використовувати для доменного сокета - це залежить від системи. Наприклад, у Linux це зазвичай „/dev/log“, а в OS/X це „/var/run/syslog“. Вам потрібно буде перевірити свою платформу та використати відповідну адресу (може знадобитися виконати цю перевірку під час виконання, якщо ваша програма має працювати на кількох платформах). У Windows ви майже повинні використовувати параметр UDP.

Примітка

On macOS 12.x (Monterey), Apple has changed the behaviour of their syslog daemon - it no longer listens on a domain socket. Therefore, you cannot expect SysLogHandler to work on this system.

See gh-91070 for more information.

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

close()

Закриває сокет для віддаленого хоста.

createSocket()

Tries to create a socket and, if it’s not a datagram socket, connect it to the other end. This method is called during handler initialization, but it’s not regarded as an error if the other end isn’t listening at this point - the method will be called again when emitting an event, if there is no socket at that point.

Added in version 3.11.

emit(record)

Запис форматується, а потім надсилається на сервер syslog. Якщо присутня інформація про винятки, вона не надсилається на сервер.

Змінено в версії 3.2.1: (Див.: bpo-12168.) У попередніх версіях повідомлення, надіслане до демонов системного журналу, завжди завершувалося нульовим байтом, оскільки ранні версії цих демонів очікували повідомлення, що завершується нульовим значенням, навіть якщо цього немає у відповідній специфікації (RFC 5424). Новіші версії цих демонов не очікують байт NUL, але видаляють його, якщо він там є, і навіть новіші демони (які більше дотримуються RFC 5424) передають байт NUL як частину повідомлення.

Щоб полегшити обробку повідомлень системного журналу, незважаючи на всі ці відмінності в поведінці демона, додавання байта NUL було зроблено конфігурованим за допомогою атрибута рівня класу, append_nul. За умовчанням це значення True (зберігаючи існуючу поведінку), але можна встановити False для екземпляра SysLogHandler, щоб цей екземпляр не додавав термінатор NUL.

Змінено в версії 3.3: (Див.: bpo-12419.) У попередніх версіях не було можливості для префікса «ident» або «tag» для визначення джерела повідомлення. Тепер це можна вказати за допомогою атрибута рівня класу, який за замовчуванням має значення "", щоб зберегти існуючу поведінку, але який можна перевизначити в екземплярі SysLogHandler, щоб цей екземпляр додавав ідентифікатор перед кожним повідомленням обробляється. Зауважте, що наданий ідентифікатор має бути текстом, а не байтами, і додається до повідомлення точно так, як є.

encodePriority(facility, priority)

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

Символічні значення LOG_ визначені в SysLogHandler і відображають значення, визначені у файлі заголовка sys/syslog.h.

Пріоритети

Ім’я (рядок)	Символічне значення
сповіщення	LOG_ALERT
crit або critical	LOG_CRIT
debug	LOG_DEBUG
emerg або panic	LOG_EMERG
помилка або помилка	LOG_ERROR
інформація	LOG_INFO
повідомлення	LOG_NOTICE
попередження або попередження	LOG_WARNING

Інфраструктура

Ім’я (рядок)	Символічне значення
автентика	LOG_AUTH
authpriv	LOG_AUTHPRIV
cron	LOG_CRON
демон	LOG_DAEMON
ftp	LOG_FTP
керн	LOG_KERN
lpr	LOG_LPR
пошта	LOG_MAIL
новини	LOG_NEWS
системний журнал	LOG_SYSLOG
користувач	LOG_USER
uucp	LOG_UUCP
локальний0	LOG_LOCAL0
локальний1	LOG_LOCAL1
локальний2	LOG_LOCAL2
локальний3	LOG_LOCAL3
локальний4	LOG_LOCAL4
локальний5	LOG_LOCAL5
локальний6	LOG_LOCAL6
локальний7	LOG_LOCAL7

mapPriority(levelname)

Зіставляє назву рівня журналювання на назву пріоритету системного журналу. Можливо, вам знадобиться перевизначити це, якщо ви використовуєте спеціальні рівні або якщо алгоритм за замовчуванням не підходить для ваших потреб. Алгоритм за замовчуванням відображає DEBUG, INFO, WARNING, ERROR і CRITICAL на еквівалентні назви системного журналу, а всі інші назви рівнів на «попередження».

NTEventLogHandler

Клас NTEventLogHandler, розташований у модулі logging.handlers, підтримує надсилання повідомлень журналу до локального журналу подій Windows NT, Windows 2000 або Windows XP. Перш ніж використовувати його, вам потрібно встановити розширення Win32 Марка Хаммонда для Python.

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

Повертає новий екземпляр класу NTEventLogHandler. Appname використовується для визначення назви програми, яка відображається в журналі подій. За допомогою цього імені створюється відповідний запис реєстру. dllname має давати повне ім’я шляху до .dll або .exe, який містить визначення повідомлень для зберігання в журналі (якщо не вказано, використовується 'win32service.pyd' — він інсталюється з розширеннями Win32 і містить деякі основні визначення повідомлень-заповнювачів. Зауважте, що використання цих заповнювачів збільшить ваші журнали подій, оскільки все джерело повідомлень зберігається в журналі. Якщо ви хочете мати менші журнали, вам потрібно передати ім’я власної .dll або .exe, який містить визначення повідомлень, які ви хочете використовувати в журналі подій). logtype є одним із 'Application', 'System' або 'Security', і за замовчуванням 'Application'.

close()

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

emit(record)

Визначає ідентифікатор повідомлення, категорію події та тип події, а потім записує повідомлення в журнал подій NT.

getEventCategory(record)

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

getEventType(record)

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

getMessageID(record)

Повертає ідентифікатор повідомлення для запису. Якщо ви використовуєте власні повідомлення, ви можете зробити це, передавши повідомлення до реєстратора як ідентифікатор, а не рядок формату. Тоді тут ви можете скористатися пошуком у словнику, щоб отримати ідентифікатор повідомлення. Ця версія повертає 1, який є основним ідентифікатором повідомлення в win32service.pyd.

SMTPHandler

Клас SMTPHandler, розташований у модулі logging.handlers, підтримує надсилання повідомлень журналу на адресу електронної пошти через SMTP.

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

Повертає новий екземпляр класу SMTPHandler. Екземпляр ініціалізується адресами відправника та одержувача та рядком теми електронного листа. toaddrs має бути списком рядків. Щоб указати нестандартний порт SMTP, використовуйте формат кортежу (хост, порт) для аргументу mailhost. Якщо ви використовуєте рядок, використовується стандартний порт SMTP. Якщо ваш сервер SMTP вимагає автентифікації, ви можете вказати кортеж (ім’я користувача, пароль) для аргументу облікові дані.

Щоб указати використання безпечного протоколу (TLS), передайте кортеж аргументу secure. Це використовуватиметься, лише якщо надано облікові дані для автентифікації. Кортеж має бути або порожнім кортежем, або кортежем з одним значенням з іменем файлу ключів, або кортежем із двома значеннями з іменами файлу ключів і файлу сертифіката. (Цей кортеж передається в метод smtplib.SMTP.starttls().)

Тайм-аут можна вказати для зв’язку з сервером SMTP за допомогою аргументу timeout.

Змінено в версії 3.3: Added the timeout parameter.

emit(record)

Форматує запис і надсилає його вказаним адресатам.

getSubject(record)

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

MemoryHandler

Клас MemoryHandler, розташований у модулі logging.handlers, підтримує буферизацію записів журналу в пам’яті, періодично скидаючи їх до обробника target. Очищення відбувається кожного разу, коли буфер заповнений або коли спостерігається подія певної або більшої серйозності.

MemoryHandler є підкласом більш загального BufferingHandler, який є абстрактним класом. Це буферизує записи журналу в пам’яті. Кожного разу, коли кожен запис додається до буфера, виконується перевірка шляхом виклику shouldFlush(), щоб побачити, чи потрібно скидати буфер. Якщо має бути, то очікується, що flush() виконає змивання.

class logging.handlers.BufferingHandler(capacity)

Ініціалізує обробник буфером зазначеної ємності. Тут ємність означає кількість буферизованих записів журналу.

emit(record)

Додайте запис до буфера. Якщо shouldFlush() повертає true, викликайте flush() для обробки буфера.

flush()

For a BufferingHandler instance, flushing means that it sets the buffer to an empty list. This method can be overwritten to implement more useful flushing behavior.

shouldFlush(record)

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

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

Повертає новий екземпляр класу MemoryHandler. Екземпляр ініціалізується з розміром буфера ємність (кількість буферизованих записів). Якщо flushLevel не вказано, використовується ERROR. Якщо ціль не вказана, ціль потрібно буде встановити за допомогою setTarget(), перш ніж цей обробник зробить щось корисне. Якщо flushOnClose вказано як False, тоді буфер не очищається, коли обробник закрито. Якщо не вказано або вказано як True, попередня поведінка очищення буфера відбуватиметься, коли обробник буде закрито.

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

close()

Викликає flush(), встановлює ціль на None і очищає буфер.

flush()

For a MemoryHandler instance, flushing means just sending the buffered records to the target, if there is one. The buffer is also cleared when buffered records are sent to the target. Override if you want different behavior.

setTarget(target)

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

shouldFlush(record)

Перевіряє заповненість буфера або запис на flushLevel або вище.

HTTPHandler

Клас HTTPHandler, розташований у модулі logging.handlers, підтримує надсилання повідомлень журналу на веб-сервер, використовуючи семантику GET або POST.

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)

Повертає новий екземпляр класу HTTPHandler. Host може мати форму host:port, якщо вам потрібно використовувати певний номер порту. Якщо метод не вказано, використовується GET. Якщо secure має значення true, використовуватиметься з’єднання HTTPS. Параметр context може бути встановлений на екземпляр ssl.SSLContext, щоб налаштувати параметри SSL, які використовуються для з’єднання HTTPS. Якщо вказано облікові дані, це має бути 2-кортеж, що складається з ідентифікатора користувача та пароля, який буде розміщено в заголовку HTTP «Авторизація» за допомогою базової автентифікації. Якщо ви вказуєте облікові дані, ви також повинні вказати secure=True, щоб ваш ідентифікатор користувача та пароль не передавалися у вигляді відкритого тексту по мережі.

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

mapLogRecord(record)

Надає словник на основі запису, який має бути закодований URL-адресою та надісланий на веб-сервер. Стандартна реалізація просто повертає record.__dict__. Цей метод можна перевизначити, якщо, наприклад, лише підмножина LogRecord має бути надіслана на веб-сервер, або якщо потрібна більш точна настройка того, що надсилається на сервер.

emit(record)

Надсилає запис на веб-сервер як словник із кодуванням URL-адреси. Метод mapLogRecord() використовується для перетворення запису в словник для надсилання.

Примітка

Оскільки підготовка запису для надсилання його на веб-сервер – це не те саме, що загальна операція форматування, використання setFormatter() для визначення Formatter для HTTPHandler не має ефекту. Замість виклику format(), цей обробник викликає mapLogRecord(), а потім urllib.parse.urlencode(), щоб закодувати словник у формі, придатній для надсилання на веб-сервер .

QueueHandler

Added in version 3.2.

Клас QueueHandler, розташований у модулі logging.handlers, підтримує надсилання повідомлень журналу до черги, таких як реалізовані в модулях queue або multiprocessing .

Разом із класом QueueListener, QueueHandler можна використовувати, щоб дозволити обробникам виконувати свою роботу в окремому потоці від того, який веде журнал. Це важливо у веб-додатках, а також в інших додатках-службах, де потоки, що обслуговують клієнтів, мають відповідати якомога швидше, тоді як будь-які потенційно повільні операції (такі як надсилання електронного листа через SMTPHandler) виконуються в окремому потоці.

class logging.handlers.QueueHandler(queue)

Повертає новий екземпляр класу QueueHandler. Примірник ініціалізується чергою для надсилання повідомлень. Чергою може бути будь-який об’єкт, подібний до черги; він використовується як є методом enqueue(), якому потрібно знати, як йому надсилати повідомлення. Для черги не обов’язково бути API відстеження завдань, що означає, що ви можете використовувати екземпляри SimpleQueue для черги.

Примітка

If you are using multiprocessing, you should avoid using SimpleQueue and instead use multiprocessing.Queue.

emit(record)

Enqueues the result of preparing the LogRecord. Should an exception occur (e.g. because a bounded queue has filled up), the handleError() method is called to handle the error. This can result in the record silently being dropped (if logging.raiseExceptions is False) or a message printed to sys.stderr (if logging.raiseExceptions is True).

prepare(record)

Готує запис для постановки в чергу. Об’єкт, повернутий цим методом, ставиться в чергу.

The base implementation formats the record to merge the message, arguments, exception and stack information, if present. It also removes unpickleable items from the record in-place. Specifically, it overwrites the record’s msg and message attributes with the merged message (obtained by calling the handler’s format() method), and sets the args, exc_info and exc_text attributes to None.

Ви можете замінити цей метод, якщо хочете перетворити запис на рядок dict або JSON або надіслати змінену копію запису, залишивши оригінал недоторканим.

Примітка

The base implementation formats the message with arguments, sets the message and msg attributes to the formatted message and sets the args and exc_text attributes to None to allow pickling and to prevent further attempts at formatting. This means that a handler on the QueueListener side won’t have the information to do custom formatting, e.g. of exceptions. You may wish to subclass QueueHandler and override this method to e.g. avoid setting exc_text to None. Note that the message / msg / args changes are related to ensuring the record is pickleable, and you might or might not be able to avoid doing that depending on whether your args are pickleable. (Note that you may have to consider not only your own code but also code in any libraries that you use.)

enqueue(record)

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

listener

When created via configuration using dictConfig(), this attribute will contain a QueueListener instance for use with this handler. Otherwise, it will be None.

Added in version 3.12.

QueueListener

Added in version 3.2.

Клас QueueListener, розташований у модулі logging.handlers, підтримує отримання повідомлень журналу з черги, таких як ті, що реалізовані в модулях queue або multiprocessing . Повідомлення отримуються з черги у внутрішньому потоці та передаються в тому самому потоці одному або кільком обробникам для обробки. Хоча QueueListener сам по собі не є обробником, він задокументований тут, оскільки він працює рука об руку з QueueHandler.

Разом із класом QueueHandler, QueueListener можна використовувати, щоб дозволити обробникам виконувати свою роботу в окремому потоці від того, який веде журнал. Це важливо у веб-додатках, а також в інших додатках-службах, де потоки, що обслуговують клієнтів, мають відповідати якомога швидше, тоді як будь-які потенційно повільні операції (такі як надсилання електронного листа через SMTPHandler) виконуються в окремому потоці.

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)

Повертає новий екземпляр класу QueueListener. Екземпляр ініціалізується чергою для надсилання повідомлень і списком обробників, які оброблятимуть записи, розміщені в черзі. Чергою може бути будь-який чергоподібний об’єкт; він передається як є до методу dequeue(), якому потрібно знати, як отримати від нього повідомлення. Для черги не обов’язково бути API відстеження завдань (хоча він використовується, якщо доступний), що означає, що ви можете використовувати екземпляри SimpleQueue для черги.

Примітка

If you are using multiprocessing, you should avoid using SimpleQueue and instead use multiprocessing.Queue.

Якщо respect_handler_level має значення True, рівень обробника враховується (порівняно з рівнем для повідомлення), коли вирішується, чи передавати повідомлення цьому обробнику; інакше, поведінка така ж, як і в попередніх версіях Python - завжди передавати кожне повідомлення кожному обробнику.

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

dequeue(block)

Вилучає запис із черги та повертає його, за бажанням блокуючи.

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

prepare(record)

Підготуйте протокол для обробки.

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

handle(record)

Обробка запису.

Це просто проходить через обробники, пропонуючи їм запис для обробки. Фактичний об’єкт, який передається обробникам, — це той, який повертається з prepare().

start()

Запускає слухача.

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

Змінено в версії 3.13.4: Raises RuntimeError if called and the listener is already running.

stop()

Зупиняє слухача.

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

enqueue_sentinel()

Записує до черги дозорний, щоб сказати слухачеві вийти. Ця реалізація використовує put_nowait(). Ви можете перевизначити цей метод, якщо хочете використовувати тайм-аути або працювати з власними реалізаціями черги.

Added in version 3.3.

Дивись також

Модуль logging

Довідник API для модуля журналювання.

Модуль logging.config

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