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

Исходный код: Lib/logging/handlers.py


В комплект поставки входят следующие полезные обработчики. Обратите внимание, что три обработчика (StreamHandler, FileHandler и NullHandler на самом деле определены в самом модуле logging, но были описаны здесь вместе с другими обработчиками.

Манипулятор потока

Класс StreamHandler, расположенный в основном пакете logging, отправляет выходные данные журнала в такие потоки, как sys.stdout, sys.stderr или любой файлоподобный объект (или, точнее, любой объект, который поддерживает write() и flush() методы).

class logging.StreamHandler(stream=None)

Возвращает новый экземпляр класса StreamHandler. Если указано значение stream, экземпляр будет использовать его для вывода в журнал; в противном случае будет использоваться sys.stderr.

emit(record)

Если указано средство форматирования, оно используется для форматирования записи. Затем запись записывается в поток, за которым следует terminator. Если присутствует информация об исключении, она форматируется с использованием traceback.print_exception() и добавляется в поток.

flush()

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

setStream(stream)

Устанавливает для потока экземпляра указанное значение, если оно отличается. Старый поток сбрасывается перед установкой нового потока.

Parameters:

stream – Поток, который должен использовать обработчик.

Result:

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

Добавлено в версии 3.7.

terminator

Строка, используемая в качестве разделителя при записи отформатированной записи в поток. Значение по умолчанию - '\n'.

Если вам не нужно завершение новой строкой, вы можете присвоить атрибуту экземпляра обработчика terminator значение пустой строки.

В более ранних версиях терминатор был жестко задан как '\n'.

Добавлено в версии 3.2.

Обработчик файлов

Класс FileHandler, расположенный в основном пакете logging, отправляет выходные данные журнала в файл на диске. Он наследует функциональность вывода от StreamHandler.

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

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

Изменено в версии 3.6: Как и строковые значения, объекты Path также принимаются в качестве аргумента filename.

Изменено в версии 3.9: Был добавлен параметр errors.

close()

Закрывает файл.

emit(record)

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

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

Обработчик нулевых значений

Добавлено в версии 3.1.

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

class logging.NullHandler

Возвращает новый экземпляр класса NullHandler.

emit(record)

Этот метод ничего не дает.

handle(record)

Этот метод ничего не дает.

createLock()

Этот метод возвращает None для блокировки, поскольку нет базового ввода-вывода, доступ к которому необходимо сериализовать.

Смотрите Настройка ведения журнала для библиотеки для получения дополнительной информации о том, как использовать NullHandler.

Просмотренный обработчик файлов

Класс WatchedFileHandler, расположенный в модуле logging.handlers, представляет собой FileHandler, который отслеживает файл, в который он записывается. Если файл изменяется, он закрывается и снова открывается с использованием имени файла.

Изменение файла может произойти из-за использования таких программ, как newsyslog и logrotate, которые выполняют ротацию файлов журнала. Этот обработчик, предназначенный для использования в Unix/Linux, отслеживает файл, чтобы увидеть, изменился ли он с момента последней отправки. (Файл считается измененным, если изменилось его устройство или индексный индекс.) Если файл изменился, старый файловый поток закрывается, а файл открывается для получения нового потока.

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

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

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

Изменено в версии 3.6: Как и строковые значения, объекты Path также принимаются в качестве аргумента filename.

Изменено в версии 3.9: Был добавлен параметр errors.

reopenIfNeeded()

Проверяет, не изменился ли файл. Если это так, существующий поток очищается и закрывается, а файл открывается снова, как правило, перед выводом записи в файл.

Добавлено в версии 3.6.

emit(record)

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

Базовый поворотный манипулятор

Класс 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(), чтобы соответствовать пользовательской схеме именования.)

Добавлено в версии 3.3.

rotator

Если для этого атрибута задано значение callable, метод rotate() делегирует этот вызываемый объект. Вызываемому объекту передаются те же параметры, что и rotate().

Добавлено в версии 3.3.

rotation_filename(default_name)

Измените имя файла журнала при ротации.

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

Реализация по умолчанию вызывает атрибут „namer“ обработчика, если он доступен для вызова, передавая ему имя по умолчанию. Если атрибут недоступен для вызова (значение по умолчанию None), имя возвращается без изменений.

Parameters:

default_name – Имя файла журнала по умолчанию.

Добавлено в версии 3.3.

rotate(source, dest)

При вращении поворачивайте текущее бревно.

Реализация по умолчанию вызывает атрибут „rotator“ обработчика, если он доступен для вызова, передавая ему аргументы source и dest. Если атрибут недоступен для вызова (значение по умолчанию None), источник просто переименовывается в конечный.

Parameters:
  • source – Имя исходного файла. Обычно это базовое имя файла, например «test.log».

  • dest – Имя файла назначения. Обычно это то, на что преобразуется исходный файл, например «test.log.1».

Добавлено в версии 3.3.

Причина, по которой существуют атрибуты, заключается в том, чтобы избавить вас от необходимости создавать подклассы - вы можете использовать одни и те же вызываемые объекты для экземпляров RotatingFileHandler и TimedRotatingFileHandler. Если вызываемый объект namer или rotator вызывает исключение, оно будет обработано таким же образом, как и любое другое исключение во время вызова emit(), т.е. с помощью метода handleError() обработчика.

Если вам нужно внести более существенные изменения в обработку ротации, вы можете переопределить эти методы.

Для примера смотрите Использование вращателя и имени для настройки обработки вращения журнала.

Вращающийся обработчик файлов

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

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

Возвращает новый экземпляр класса RotatingFileHandler. Указанный файл открывается и используется в качестве потока для ведения журнала. Если mode не указан, используется 'a'. Если значение encoding не равно 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)

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

Обработчик изменяющегося по времени файла

Класс 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 и interval.

Вы можете использовать when, чтобы указать тип интервала. Список возможных значений приведен ниже. Обратите внимание, что они не учитывают регистр символов.

Ценность

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

Если/как используется atTime

'S'

Секунд

Игнорируется

'M'

Минут

Игнорируется

'H'

Часов

Игнорируется

'D'

Дни

Игнорируется

'W0'-'W6'

День недели (0=понедельник)

Используется для вычисления начального времени опрокидывания

'midnight'

Переход в полночь, если время не указано, в противном случае в то же время время

Используется для вычисления начального времени опрокидывания

При использовании ротации по дням недели укажите «W0» для понедельника, «W1» для вторника и так далее до «W6» для воскресенья. В этом случае значение, переданное для interval, не используется.

Система сохранит старые файлы журнала, добавив расширения к имени файла. Расширения основаны на дате и времени, используя формат 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()

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

Обработчик носков

Класс 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, расположенный в модуле logging.handlers, наследуется от SocketHandler для поддержки отправки сообщений журнала через UDP-сокеты.

class logging.handlers.DatagramHandler(host, port)

Возвращает новый экземпляр класса DatagramHandler, предназначенный для взаимодействия с удаленной машиной, адрес которой задан через host и port.

Примечание

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

Изменено в версии 3.4: Если port указано как None, доменный сокет Unix создается с использованием значения в host - в противном случае создается UDP-сокет.

emit()

Извлекает словарь атрибутов записи и записывает его в сокет в двоичном формате. Если с сокетом произошла ошибка, пакет автоматически удаляется. Чтобы преобразовать запись на принимающей стороне в LogRecord, используйте функцию makeLogRecord().

makeSocket()

Заводской метод SocketHandler здесь переопределен для создания UDP-сокета (socket.SOCK_DGRAM).

send(s)

Отправьте выбранную байтовую строку в сокет. Формат отправляемой байтовой строки соответствует описанию в документации для SocketHandler.makePickle().

Системный обработчик

Класс SysLogHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журнала в удаленный или локальный системный журнал Unix.

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

Возвращает новый экземпляр класса SysLogHandler, предназначенный для взаимодействия с удаленной Unix-машиной, адрес которой задается через address в виде кортежа (host, port). Если address не указан, используется ('localhost', 514). Адрес используется для открытия сокета. Альтернативой предоставлению кортежа (host, port) является предоставление адреса в виде строки, например „/dev/log“. В этом случае для отправки сообщения в системный журнал используется сокет домена Unix. Если facility не указан, используется LOG_USER. Тип открываемого сокета зависит от аргумента socktype, который по умолчанию равен socket.SOCK_DGRAM и, таким образом, открывает UDP-сокет. Чтобы открыть TCP-сокет (для использования с более новыми демонами системного журнала, такими как rsyslog), укажите значение socket.SOCK_STREAM.

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

Примечание

В Mac OS 12.x (Monterey) Apple изменила поведение своего демона системного журнала - он больше не прослушивает доменный сокет. Таким образом, вы не можете ожидать, что SysLogHandler будет работать в этой системе.

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

Изменено в версии 3.2: был добавлен socktype.

close()

Закрывает соединение с удаленным хостом.

createSocket()

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

Добавлено в версии 3.11.

emit(record)

Запись форматируется и затем отправляется на сервер системного журнала. Если информация об исключении присутствует, она не отправляется на сервер.

Изменено в версии 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.

Приоритеты

Имя (строка)

Символическое значение

alert

ЛОГ_АЛЕРТ

crit или critical

ЛОГ_КРИТ

debug

ЛОГ_ДЕБУГ

emerg или panic

ЛОГ_ЭМЕРГИЯ

err или error

ЛОГ_ЕРР

info

ЛОГ_ИНФО

notice

ЛОГ_ПРИМЕЧАНИЕ

warn или warning

ЛОГ_ОБЪЯВЛЕНИЕ

Удобства

Имя (строка)

Символическое значение

auth

ЛОГ_AUTH

authpriv

ЛОГ_АВТОРИЗОВАННЫЙ ДОСТУП

cron

ЛОГ_КРОН

daemon

ЛОГ_ДЕМОН

ftp

ЛОГ_FTP

kern

ЛОГ_КЕРН

lpr

ЛОГ_LPR

mail

ЛОГ_МАЙЛ

news

ЛОГ_НОВОСТИ

syslog

ЛОГ_SYSLOG

user

ЛОГ_ ПОЛЬЗОВАТЕЛЯ

uucp

ЛОГ_UUCP

local0

ЛОГ_ЛОКАЛЬНЫЙ 0

local1

ЛОГ_ЛОКАЛЬНЫЙ1

local2

ЛОГ_ЛОКАЛЬНЫЙ2

local3

ЛОГ_ЛОКАЛЬ3

local4

ЛОГ_ЛОКАЛЬ4

local5

ЛОГ_ЛОКАЛЬНЫЙ5

local6

ЛОГ_ЛОКАЛЬ6

local7

ЛОГ_ЛОКАЛЬ7

mapPriority(levelname)

Сопоставляет имя уровня ведения журнала с именем приоритета системного журнала. Возможно, вам потребуется переопределить это, если вы используете пользовательские уровни или если алгоритм по умолчанию не подходит для ваших нужд. Алгоритм по умолчанию преобразует DEBUG, INFO, WARNING, ERROR и CRITICAL в эквивалентные имена системных журналов, а все остальные имена уровней - в «предупреждение».

Обработчик событий

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

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

Возвращает новый экземпляр класса NTEventLogHandler. appname используется для определения имени приложения в том виде, в каком оно отображается в журнале событий. С использованием этого имени создается соответствующая запись в реестре. В dllname должен быть указан полный путь к a .библиотека 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)

Возвращает идентификатор сообщения для записи. Если вы используете свои собственные сообщения, вы можете сделать это, передав msg в программу регистрации в качестве идентификатора, а не строки формата. Затем, здесь, вы можете использовать поиск по словарю, чтобы получить идентификатор сообщения. Эта версия возвращает значение 1, которое является базовым идентификатором сообщения в win32service.pyd.

Обработчик SMTPHandler

Класс SMTPHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журнала на адрес электронной почты по протоколу SMTP.

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

Возвращает новый экземпляр класса SMTPHandler. Экземпляр инициализируется адресами from и to, а также строкой темы электронного письма. toaddrs должен представлять собой список строк. Чтобы указать нестандартный SMTP-порт, используйте формат кортежа (host, port) в качестве аргумента mailhost. Если используется строка, то используется стандартный SMTP-порт. Если вашему SMTP-серверу требуется аутентификация, вы можете указать кортеж (имя пользователя, пароль) для аргумента credentials.

Чтобы указать использование защищенного протокола (TLS), передайте в виде кортежа аргумент secure. Он будет использоваться только при указании учетных данных для аутентификации. Кортеж должен быть либо пустым, либо состоящим из одного значения с именем ключевого файла, либо состоящим из 2 значений с именами ключевого файла и файла сертификата. (Этот кортеж передается в метод smtplib.SMTP.starttls().)

Время ожидания может быть указано для связи с SMTP-сервером с помощью аргумента timeout.

Изменено в версии 3.3: Добавлен параметр timeout.

emit(record)

Форматирует запись и отправляет ее по указанным адресам.

getSubject(record)

Если вы хотите указать строку темы, которая зависит от записи, переопределите этот метод.

Обработчик памяти

Класс 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. Экземпляр инициализируется с размером буфера capacity (количество буферизованных записей). Если значение flushLevel не указано, используется значение ERROR. Если цель не указана, то цель нужно будет задать с помощью setTarget(), прежде чем этот обработчик сделает что-либо полезное. Если значение flushOnClose указано как False, то буфер не очищается при закрытии обработчика. Если не указано или указано как True, то при закрытии обработчика произойдет предыдущее действие по очистке буфера.

Изменено в версии 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:port, если вам нужно использовать определенный номер порта. Если не указан метод, используется GET. Если значение secure равно true, будет использоваться HTTPS-соединение. Параметру context может быть присвоено значение ssl.SSLContext для настройки параметров SSL, используемых для HTTPS-соединения. Если указан параметр credentials, то это должен быть кортеж из 2 элементов, состоящий из идентификатора пользователя и пароля, который будет помещен в заголовок HTTP „Authorization“ с использованием базовой аутентификации. Если вы указываете учетные данные, вам также следует указать secure=True, чтобы ваш идентификатор пользователя и пароль не передавались открытым текстом по сети.

Изменено в версии 3.5: Был добавлен параметр context.

mapLogRecord(record)

Предоставляет словарь, основанный на record, который должен быть закодирован в URL-адрес и отправлен на веб-сервер. Реализация по умолчанию просто возвращает record.__dict__. Этот метод может быть переопределен, если, например, на веб-сервер должно быть отправлено только подмножество LogRecord, или если требуется более конкретная настройка того, что отправляется на сервер.

emit(record)

Отправляет запись на веб-сервер в виде словаря в кодировке URL. Метод mapLogRecord() используется для преобразования записи в словарь, который будет отправлен.

Примечание

Поскольку подготовка записи для отправки на веб-сервер отличается от обычной операции форматирования, использование setFormatter() для указания Formatter вместо HTTPHandler не имеет никакого эффекта. Вместо вызова format() этот обработчик вызывает mapLogRecord(), а затем urllib.parse.urlencode(), чтобы закодировать словарь в форме, подходящей для отправки на веб-сервер.

Обработчик очереди

Добавлено в версии 3.2.

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

Наряду с классом QueueListener, QueueHandler может использоваться для того, чтобы позволить обработчикам выполнять свою работу в отдельном потоке, отличном от того, который выполняет ведение журнала. Это важно в веб-приложениях, а также в других сервисных приложениях, где потоки, обслуживающие клиентов, должны реагировать как можно быстрее, в то время как любые потенциально медленные операции (например, отправка электронного письма через SMTPHandler) выполняются в отдельном потоке.

class logging.handlers.QueueHandler(queue)

Возвращает новый экземпляр класса QueueHandler. Экземпляр инициализируется с помощью очереди для отправки сообщений. queue может быть любым объектом, подобным очереди; он используется как есть методом enqueue(), который должен знать, как отправлять ему сообщения. Очередь не требуется для наличия API отслеживания задач, что означает, что вы можете использовать SimpleQueue экземпляра для очереди.

Примечание

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

emit(record)

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

prepare(record)

Подготавливает запись для постановки в очередь. Объект, возвращаемый этим методом, помещается в очередь.

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

Возможно, вам захочется переопределить этот метод, если вы хотите преобразовать запись в строку dict или JSON или отправить измененную копию записи, оставив оригинал нетронутым.

Примечание

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

enqueue(record)

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

Слушатель в очереди

Добавлено в версии 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 экземпляра для очереди.

Примечание

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

Если respect_handler_level это True, обработчик уровень уважают (по сравнению с уровнем за сообщение) при решении вопроса о том, чтобы передавать сообщения, что обработчик; в противном случае поведение, как и в предыдущие версии Python - всегда проходят каждое сообщение, чтобы каждый обработчик.

Изменено в версии 3.5: Был добавлен аргумент respect_handler_level.

dequeue(block)

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

В базовой реализации используется get(). Возможно, вы захотите переопределить этот метод, если хотите использовать тайм-ауты или работать с пользовательскими реализациями очередей.

prepare(record)

Подготовьте запись для обработки.

Эта реализация просто возвращает переданную запись. Возможно, вы захотите переопределить этот метод, если вам нужно выполнить какую-либо пользовательскую сортировку или манипуляцию с записью перед передачей ее обработчикам.

handle(record)

Обработайте запись.

Это просто перебирает обработчики, предлагая им запись для обработки. Фактический объект, передаваемый обработчикам, - это тот, который возвращается из prepare().

start()

Запускает прослушиватель.

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

stop()

Останавливает прослушивателя.

Это запрашивает завершение работы потока, а затем ожидает, пока он это сделает. Обратите внимание, что если вы не вызовете это до завершения работы вашего приложения, в очереди могут остаться некоторые записи, которые не будут обработаны.

enqueue_sentinel()

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

Добавлено в версии 3.3.

См.также

Модуль logging

Ссылка на API для модуля ведения журнала.

Модуль logging.config

API настройки для модуля ведения журнала.

Вернуться на верх