logging.handlers — Обработчики журналирования

Kod źródłowy: Lib/logging/handlers.py

Наступні корисні обробники надаються в пакеті. Зауважте, що три обробники (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)

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

Parametry:

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

Zwraca:

старый поток, если поток был изменен, или «Нет», если это не так.

Dodane w wersji 3.7.

terminator

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

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

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

Dodane w wersji 3.2.

FileHandler

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

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

Возвращает новый экземпляр класса FileHandler. Указанный файл открывается и используется в качестве потока для протоколирования. Если mode не указан, используется 'a'. Если кодировка не равна «Нет», она используется для открытия файла с этой кодировкой. Если delay имеет значение true, то открытие файла откладывается до первого вызова emit(). По умолчанию файл растет бесконечно. Если указано errors, оно используется для определения способа обработки ошибок кодирования.

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

Zmienione w wersji 3.9: Додано параметр errors.

close()

Menutup berkas.

emit(record)

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

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

NullHandler

Dodane w wersji 3.1.

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

class logging.NullHandler

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

emit(record)

Metode ini tidak melakukan apa pun.

handle(record)

Metode ini tidak melakukan apa pun.

createLock()

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

Перегляньте Configuring Logging for a Library, щоб дізнатися більше про використання 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)

Возвращает новый экземпляр класса WatchedFileHandler. Указанный файл открывается и используется в качестве потока для протоколирования. Если mode не указан, используется 'a'. Если кодировка не равна «Нет», она используется для открытия файла с этой кодировкой. Если delay имеет значение true, то открытие файла откладывается до первого вызова emit(). По умолчанию файл растет бесконечно. Если указано errors, оно определяет, как обрабатываются ошибки кодирования.

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

Zmienione w wersji 3.9: Додано параметр errors.

reopenIfNeeded()

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

Dodane w wersji 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().

Informacja

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

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

Dodane w wersji 3.3.

rotator

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

Dodane w wersji 3.3.

rotation_filename(default_name)

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

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

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

Parametry:

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

Dodane w wersji 3.3.

rotate(source, dest)

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

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

Parametry:

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

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

Dodane w wersji 3.3.

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

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

Для прикладу перегляньте Using a rotator and namer to customize log rotation processing.

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 тощо.

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

Zmienione w wersji 3.9: Додано параметр errors.

doRollover()

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

emit(record)

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

shouldRollover(record)

确定所提供的记录是否会导致文件超出已配置的大小限制。

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, щоб вказати тип інтервалу. Нижче наведено список можливих значень. Зауважте, що вони не чутливі до регістру.

Wartość

Тип інтервалу

Якщо/як використовується atTime

'S'

Detik

Ігнорується

'M'

Menit

Ігнорується

'H'

Jam

Ігнорується

'D'

Hari

Ігнорується

'W0'-'W6'

День тижня (0=понеділок)

Використовується для обчислення початкового часу перекидання

'midnight'

Перехід опівночі, якщо 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, воно використовується для визначення способу обробки помилок кодування.

Informacja

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

Zmienione w wersji 3.4: Додано параметр atTime.

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

Zmienione w wersji 3.9: Додано параметр errors.

doRollover()

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

emit(record)

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

getFilesToDelete()

返回一个由应当作为轮转的一部分被删除的文件名组成的列表。 这些

shouldRollover(record)

确定是否经过了足够的时间使轮转应当发生，并在确实如此时计算下一次轮转的时间。

SocketHandler

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

class logging.handlers.SocketHandler(host, port)

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

Zmienione w wersji 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.

Informacja

Поскольку UDP не является протоколом потоковой передачи, между экземпляром этого обработчика и хостом не существует постоянного соединения. По этой причине при использовании сетевого сокета может потребоваться выполнять поиск DNS каждый раз при регистрации события, что может привести к некоторой задержке в системе. Если это вас затрагивает, вы можете выполнить поиск самостоятельно и инициализировать этот обработчик, используя найденный IP-адрес, а не имя хоста.

Zmienione w wersji 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)

Returns a new instance of the SysLogHandler class intended to communicate with a remote Unix machine whose address is given by address in the form of a (host, port) tuple. If address is not specified, ('localhost', 514) is used. The address is used to open a socket. An alternative to providing a (host, port) tuple is providing an address as a string, for example «/dev/log». In this case, a Unix domain socket is used to send the message to the syslog. If facility is not specified, LOG_USER is used. The type of socket opened depends on the socktype argument, which defaults to socket.SOCK_DGRAM and thus opens a UDP socket. To open a TCP socket (for use with the newer syslog daemons such as rsyslog), specify a value of socket.SOCK_STREAM.

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

Informacja

В macOS 12.x (Монтерей) Apple изменила поведение своего демона системного журнала — он больше не прослушивает сокет домена. Следовательно, вы не можете ожидать, что SysLogHandler будет работать в этой системе.

См. gh-91070 для получения дополнительной информации.

Zmienione w wersji 3.2: Додано socktype.

close()

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

createSocket()

Пытается создать сокет и, если это не дейтаграммный сокет, подключить его к другому концу. Этот метод вызывается во время инициализации обработчика, но он не считается ошибкой, если другой конец в этот момент не прослушивает — метод будет вызываться снова при отправке события, если в этот момент нет сокета.

Dodane w wersji 3.11.

emit(record)

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

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

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

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

encodePriority(facility, priority)

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

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

Пріоритети

Nama (string)

Символічне значення

alert

LOG_ALERT

crit or critical

LOG_CRIT

debug

LOG_DEBUG

emerg or panic

LOG_EMERG

err or error

LOG_ERR

info

LOG_INFO

notice

LOG_NOTICE

warn or warning

LOG_WARNING

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

Nama (string)

Символічне значення

auth

LOG_AUTH

authpriv

LOG_AUTHPRIV

cron

LOG_CRON

daemon

LOG_DAEMON

ftp

LOG_FTP

kern

LOG_KERN

lpr

LOG_LPR

mail

LOG_MAIL

news

LOG_NEWS

syslog

LOG_SYSLOG

user

LOG_USER

uucp

LOG_UUCP

local0

LOG_LOCAL0

local1

LOG_LOCAL1

local2

LOG_LOCAL2

local3

LOG_LOCAL3

local4

LOG_LOCAL4

local5

LOG_LOCAL5

local6

LOG_LOCAL6

local7

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.

Zmienione w wersji 3.3: Добавлен параметр timeout.

emit(record)

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

getSubject(record)

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

MemoryHandler

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

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

class logging.handlers.BufferingHandler(capacity)

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

emit(record)

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

flush()

Для экземпляра BufferingHandler очистка означает, что буфер устанавливается в пустой список. Этот метод можно перезаписать, чтобы реализовать более полезное поведение очистки.

shouldFlush(record)

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

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

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

Zmienione w wersji 3.6: Додано параметр flushOnClose.

close()

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

flush()

Для экземпляра MemoryHandler очистка означает просто отправку буферизованных записей в цель, если таковая имеется. Буфер также очищается, когда буферизованные записи отправляются в цель. Переопределите, если хотите другое поведение.

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, щоб ваш ідентифікатор користувача та пароль не передавалися у вигляді відкритого тексту по мережі.

Zmienione w wersji 3.5: Додано параметр context.

mapLogRecord(record)

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

emit(record)

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

Informacja

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

QueueHandler

Dodane w wersji 3.2.

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

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

class logging.handlers.QueueHandler(queue)

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

Informacja

Если вы используете multiprocessing, вам следует избегать использования SimpleQueue и вместо этого использовать multiprocessing.Queue.

Ostrzeżenie

multiprocessing 模块使用一个通过 get_logger() 创建和访问的内部记录器。 multiprocessing.Queue 将记录正在排队的项目的 DEBUG 级消息。 如果这些日志消息由 QueueHandler 使用相同的 multiprocessing.Queue 实例进行处理，则会导致死锁或无限递归。

emit(record)

Ставит в очередь результат подготовки LogRecord. В случае возникновения исключения (например, из-за заполнения ограниченной очереди) для обработки ошибки вызывается метод handleError(). Это может привести к молчаливому удалению записи (если logging.raiseExceptions имеет значение False) или к выводу сообщения в sys.stderr (если logging.raiseExceptions` имеет значение `` «Правда»).

prepare(record)

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

Базовая реализация форматирует запись для объединения сообщения, аргументов, исключений и информации стека, если они есть. Он также удаляет неподдающиеся редактированию элементы из записи на месте. В частности, он перезаписывает атрибуты записи msg и message объединенным сообщением (полученным путем вызова метода format() обработчика) и устанавливает args, : Для атрибутов attr:exc_info и exc_text установлено значение None.

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

Informacja

Базовая реализация форматирует сообщение с аргументами, устанавливает атрибуты message и msg для отформатированного сообщения и устанавливает атрибуты args и exc_text в None, чтобы разрешить травление и предотвращение дальнейших попыток форматирования. Это означает, что обработчик на стороне QueueListener не будет иметь информации для выполнения пользовательского форматирования, например, исключений. Вы можете создать подкласс QueueHandler и переопределить этот метод, чтобы, например, не устанавливать для exc_text значение None. Обратите внимание, что изменения message/msg/args связаны с обеспечением возможности выбора записи, и вы можете или не можете избежать этого в зависимости от того, есть ли у вас ``args` ` можно мариновать. (Обратите внимание, что вам, возможно, придется учитывать не только свой собственный код, но и код любых библиотек, которые вы используете.)

enqueue(record)

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

listener

При создании с помощью конфигурации с использованием dictConfig() этот атрибут будет содержать экземпляр QueueListener для использования с этим обработчиком. В противном случае это будет None.

Dodane w wersji 3.12.

QueueListener

Dodane w wersji 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 для черги.

Informacja

Если вы используете multiprocessing, вам следует избегать использования SimpleQueue и вместо этого использовать multiprocessing.Queue.

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

Zmienione w wersji 3.5: Додано аргумент respect_handler_level.

dequeue(block)

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

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

prepare(record)

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

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

handle(record)

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

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

start()

Memulai listener.

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

Zmienione w wersji 3.13.4: 如果被调用时监听器已在运行则会引发 RuntimeError。

stop()

Menghentikan listener.

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

enqueue_sentinel()

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

Dodane w wersji 3.3.

Zobacz także

Модуль logging

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

Модуль logging.config

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