# `logging.handlers` — Logging handlers

Вихідний код: 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)

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

    Параметри:

      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, timeout=None)

  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`. If timeout is specified, it sets a timeout (in seconds) for the socket operations. This can help prevent the program from hanging indefinitely if the syslog server is unreachable. By default, timeout is `None`, meaning no timeout is applied.

  Зауважте, що якщо ваш сервер не прослуховує 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.

  Змінено в версії 3.14: timeout was added.

  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`.

  Попередження

  The `multiprocessing` module uses an internal logger created and accessed via `get_logger()`. `multiprocessing.Queue` will log `DEBUG` level messages upon items being queued. If those log messages are processed by a `QueueHandler` using the same `multiprocessing.Queue` instance, it will cause a deadlock or infinite recursion.

  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`.

  Змінено в версії 3.14: `QueueListener` can now be used as a context manager via `with`. When entering the context, the listener is started. When exiting the context, the listener is stopped. `__enter__()` returns the `QueueListener` object.

  dequeue(block)

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

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

  prepare(record)

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

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

  handle(record)

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

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

  start()

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

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

    Змінено в версії 3.14: 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 конфігурації для модуля журналювання.