polog 0.0.11

Удобный асинхронный логгер

Polog - удобный асинхронный логгер

Упростите логирование в ваших проектах, выкинув ненужный код. Вот список некоторых преимуществ логгера Polog:

• Минималистичный синтаксис без визуального мусора. Достаточно одной функции, которую можно вызывать непосредственно, а можно использовать в качестве универсального декоратора для функций и классов. Вам не придется долго разбираться в том, как это работает, поскольку проще уже не придумаешь.
• Поддержка асинхронности. Декоратор для автоматического логирования работает как на обычных функциях, так и на корутинах.
• Высокая производительность. Записи делаются из отдельных потоков и ввод-вывод не блокирует основной поток исполнения вашей программы.
• Автоматическое логирование. Просто повесьте декоратор на вашу функцию или класс, и каждый вызов будет логироваться автоматически (или только ошибки - это легко настроить).
• Удобное профилирование. Время работы функций записывается. Вы можете накопить статистику производительности вашего кода и легко ее анализировать.
• Учтено, что может быть несколько сервисов, которые пишут в одно место. Их можно будет различить.
• Вы можете писать собственные обработчики или пользоваться уже существующими. К примеру, вы можете настроить отправку уведомлений об ошибках по электронной почте.

Оглавление

• Быстрый старт
• Общая схема работы
• Уровни логирования
• Настройки логгера
• log() - одна функция, чтобы править всеми
• Декорируем функции
• Декорируем классы
• Перекрестное декорирование
• Запрет логирования через декоратор @logging_is_forbidden
• Редактируем автоматические логи из задекорированных функций
• "Ручное" логирование
• Добавляем собственные поля
• Обработчики
• Вывод в файл или в консоль, ротация логов
• Как включить уведомления по электронной почте
• Пишем свой обработчик
• Общие советы про логирование

Быстрый старт

Установите Polog через pip:

$ pip install polog

Прежде, чем вызывать логгер, необходимо зарегистрировать обработчик для записей:

from polog import config, file_writer


config.add_handlers(file_writer('file.log'))

Теперь наши логи будут выводиться в файл file.log.

Импортируем объект log и применим его к вашей функции как декоратор:

from polog import log


@log
def sum(a, b):
  return a + b

print(sum(2, 2))

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

Теперь попробуем залогировать ошибку:

@log
def division(a, b):
  return a / b

print(division(2, 0))

Делим число на 0. Что вывелось на этот раз? Очевидно, результат работы функции выведен не будет, т.к. она не успела ничего вернуть. Зато там появится подробная информация об ошибке: название поднятого исключения, текст его сообщения, трейсбек и даже локальные переменные. Кроме того, появится отметка о неуспешности выполненной операции - они проставляются ко всем автоматическим логам, чтобы их легче было фильтровать.

Еще небольшой пример кода:

@log
def division(a, b):
  return a / b

@log
def operation(a, b):
  return division(a, b)

print(operation(2, 0))

Чего в нем примечательного? В данном случае ошибка происходит в функции division(), а затем, поднимаясь по стеку вызовов, она проходит через функцию operation(). Однако логгер записал сообщение об ошибке только один раз! Встретив исключение в первый раз, он его записывает и подменяет другим, специальным, которое игнорирует в дальнейшем. В результате ваше хранилище логов не засоряется бесконечным дублированием информации об ошибках.

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

Что, если мы хотим залогировать все методы целого класса? Обязательно ли проходиться ним вручную и на каждый вешать по декоратору? Нет! Классы тоже можно декорировать:

@log
class OneOperation(object):
  def division(self, a, b):
    return a / b

  def operation(self, a, b):
    return self.division(a, b)

print(OneOperation().operation(2, 0))

Если вам все же не хватило автоматического логирования, вы можете писать логи вручную, вызывая log() как функцию из своего кода:

log("All right!")
log("It's bad.", exception=ValueError("Example of an exception."))

На этом введение закончено. Если вам интересны тонкости настройки логгера и его более мощные функции, можете почитать более подробную документацию.

Как это все работает?

Процесс выполнения любой программы состоит из событий: вызываются функции, поднимаются исключения и т. д. Эти события, в свою очередь, состоят из других событий, масштабом поменьше. Задача логгера - записать максимально подробный отчет обо всем этом, чтобы программист в случае сбоя мог быстро обнаружить место ошибки и устранить ее. Записать все события до мельчайших деталей невозможно - данных было бы слишком много. Поэтому обычно человек непосредственно указывает места в программном коде, записи из которых его интересуют. На этом принципе построен модуль логирования из стандартной библиотеки.

Обычно вызовы стандартного логгера в коде выглядят как-то так:

import logging


logging.debug('Skip this message!')
logging.info("Sometimes it's interesting.")
logging.warning('This is serious.')
logging.error('PANIC')
logging.critical("I'm quitting.")

В разных ситуациях нам нужно получать разное количество информации из программы: от максимальной подробности на этапе разработки, до редких записей об ошибках и иных важных событиях при реальной эксплуатации. Чтобы не лазить по всему коду и не исправлять / удалять каждый вызов логгера, мы манипулируем лишь общим уровнем логгирования. Необходимый уровень важности записи является фильтром, который устанавливается глобально по всей программе.

В чем отличие Polog от описанной схемы? Больших отличий по принципу действия тут нет. Программа все так же производит события, а мы их записываем или нет, в зависимости от выбранного уровня логирования. Задача библиотеки - по возможности, максимально очистить код ваших функций от визуального мусора, создаваемого вызовами логгеров. Дело в том, что большинство событий, записываемых логгерами, вполне стандартны. Программисту обычно интересно знать, что программа "зашла" в какой-то блок кода, или что в каком-то блоке было поднято исключение. Но если программа написана хорошо и ее логические части разбиты на независимые функции, нам нет нужды залезать в них, чтобы записать все эти вещи. Достаточно обернуть их вызов в декоратор, который сделает все сам.

С появлением декоратора возникают новые вопросы. Если у меня большой класс с кучей методов, мне что, на каждый метод навешивать декоратор? Если навесить его на одну функцию несколько раз, он при каждом вызове будет несколько записей делать? Что, если исключение пройдет через несколько таких задекорированных функций по стеку вызовов - оно много раз запишется? Как быть, если я точно не хочу, чтобы информация из какой-то функции вылезала наружу, например если там важные клиентские данные? Это все работает только на обычных функциях, или на корутинах тоже?

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

Помимо интерфейса регистрации событий, Polog немного отличается и по внутреннему устройству. Схема его работы выглядит примерно так:

• События "ловятся" через декораторы или когда вы вызываете логгер вручную.
• У каждого события определяется важность. Если важность выше или равна текущему уровню логирования, мы работаем с событием дальше. Если нет, логгер не делает с ним больше ничего.
• Из события извлекаются данные. Когда оно произошло? В каком месте кода? Было ли исключение? И еще несколько вопросов, ответы на которые записываются в некое промежуточное представление.
• Промежуточное представление кладется в очередь на запись.
• В эту очередь смотрят несколько "воркеров" из отдельных потоков. Как только один из них освобождается, он может взять следующий лог из очереди и записать его. Числом потоков с воркерами вы можете управлять, по умолчанию их 2.
• Получив объект промежуточного представления события, воркер последовательно передает его в каждый из имеющихся у него обработчиков.
• Обработчики делают с событием кто что умеет: записывают в файл, отправляют по почте, отправляют на внешние сервисы и т. д.

Вы как пользователь библиотеки можете использовать готовые обработчики или писать свои. Кроме того, вы можете гибко настраивать критерии, по которым определяется, записывать событие или нет.

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

Уровни логирования

Уровни логирования - это универсальный и удобный способ разделить все события на группы, и разбить эти группы на две части: одну мы логируем, а другую - нет. "Разделителем" служит глобальный уровень логирования, его мы устанавливаем для всей программы. Каждое событие также имеет пометку об уровне. Если уровень события больше, чем глобальный, или равен ему, оно будет записано, а иначе - проигнорировано. Вы можете не указывать при каждом вызове логгера уровень, которым будут помечаться отслеживаемые им события. В этом случае события будут помечаться уровнями по умолчанию. Для обычных событий уровнем по умолчанию является 1, для ошибок (например, когда в задекорированной логгером функции происходит исключение) - 2. Однако это можно изменить.

В декораторе вы можете указать уровень, которым будут помечаться все вызовы соответствующей функции:

from polog import log


@log(level=5)
def sum(a, b):
  return a + b

print(sum(2, 2))
# Запишется лог с меткой 5 уровня.

Это доступно при декорировании как функций, так и классов, работает одинаково.

В декораторе вы также можете установить метку уровня, которой будут помечаться только ошибки:

@log(level=5, error_level=10)

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

Также вы можете установить отдельный уровень логирования по умолчанию для ошибок глобально через настройки:

from polog import config


config.set(error_level=50)

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

Уровням логирования можно присвоить имена и в дальнейшем использовать их вместо чисел:

from polog import log, config


# Присваиваем уровню 5 имя 'ERROR', а уровню 1 - 'ALL'.
config.levels(ERROR=5, ALL=1)

# Используем присвоенное имя вместо номера уровня.
@log(level='ERROR')
def sum(a, b):
  return a + b

print(sum(2, 2))
# Запишется лог с меткой 5 уровня.

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

Также, зарегистрировав имена уровней логирования, вы можете указывать их через точку, причем как при использовании объекта log в качестве декоратора, так и при "ручном" логировании:

from polog import log, config


config.levels(halloween_level=13)

@log.halloween_level
def scary_function(a, b):
  ...

print(scary_function('friday', 13))
# Запишется лог 13-го уровня.
log.halloween_level('boo!')
# Также запишется лог 13-го уровня.

Если вы привыкли пользоваться стандартным модулем logging, вы можете присвоить уровням логирования стандартные имена оттуда:

from polog import log, config


# Имена уровням логирования проставляются автоматически, в соответствии со стандартной схемой.
config.standart_levels()

@log(level='ERROR')
def sum(a, b):
  return a + b

print(sum(2, 2))
# Запишется лог с меткой 40 уровня.

Общим уровнем логирования вы можете управлять через настройки:

from polog import log, config


# Имена уровням логирования проставляются автоматически, в соответствии со стандартной схемой.
config.standart_levels()

# Устанавливаем текущий уровень логирования - 'CRITICAL'.
config.set(level='CRITICAL')

@log(level='ERROR')
def sum(a, b):
  return a + b

print(sum(2, 2))
# Запись произведена не будет, т. к. уровень сообщения 'ERROR' ниже текущего уровня логирования 'CRITICAL'.

Все события уровнем ниже игнорируются.

Общие настройки

Выше уже упоминалось, что общие настройки логирования можно делать через класс config. Давайте вспомним, откуда его нужно импортировать:

from polog import config

Класс config предоставляет несколько методов. Все они работают непосредственно от класса, без вызова __init__, например вот так:

config.set(pool_size=5)

Методы класса config:

• set(): общие настройки логгера.

  Принимает следующие именованные параметры:

  pool_size (int) - количество потоков-воркеров, по умолчанию равное 2-м. Вы можете увеличить это число, если ваша программа пишет логи достаточно интенсивно. Но помните, что большое число потоков - это большая ответственность дополнительные потоки повышают накладные расходы интерпретатора и могут замедлить вашу программу.

  service_name (str) - имя сервиса. Указывается в каждой записи. По умолчанию 'base'.

  level (int, str) - общий уровень логирования. События уровнем ниже записываться не будут.

  errors_level (int, str) - уровень логирования для ошибок. По умолчанию он равен 2-м.

  original_exceptions (bool) - режим оригинальных исключений. По умолчанию False. True означает, что все исключения остаются как были и никак не видоизменяются логгером. Это может приводить к дублированию информации об одной ошибке в записях, т. к. исключение, поднимаясь по стеку вызовов функций, может пройти через несколько задекорированных логгером функций. В режиме False все исключения логируются 1 раз, после чего оригинальное исключение подменяется на LoggedError, которое не логируется никогда.

  delay_before_exit (int, float) - задержка перед завершением программы для записи оставшихся логов. При завершении работы программы может произойти небольшая пауза, в течение которой будут записаны оставшиеся логи из очереди. Максимальная продолжительность такой паузы указывается в данной настройке.

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

• levels(): присвоение имен уровням логирования.

• standart_levels(): присвоение стандартных имен уровням логирования.

• add_handlers(): регистрация новых обработчиков.

• get_handlers(): получить словарь с обработчиками.

• delete_handlers(): удаление обработчиков.

• add_fields(): регистрация новых полей лога.

• delete_fields(): удаление ранее зарегистрированных полей лога. Стандартные поля удалить нельзя.

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

log() - одна функция, чтобы править всеми

Polog максимально упрощает логирование, предоставляя вам один объект, который можно использовать как для ручной регистрации логов, так и в качестве декоратора. Импортируется он так:

from polog import log

В нескольких разделах ниже вы можете узнать подробности о том, как он работает.

Декорируем функции

Объект log может быть использован как декоратор для автоматического логирования вызовов функций. Поддерживает как обычные функции, так и корутинные.

@log можно использовать как со скобками, так и без. Вызов без скобок эквивалентен вызову со скобками, но без аргументов.

Параметр message можно использовать для добавления произвольного текста к каждому логу.

from polog import log


@log(message='This function is very important!!!')
def very_important_function():
  ...

Про управление уровнями логирования через аргументы к данному декоратору читайте в разделе "уровни логирования".

Если в задекорированной функции возникло необработанное исключение, по умолчанию @log записывает его, после чего подменяет внутренним исключением LoggedError. В дальнейшем, если логгеру встречается это исключение, оно игнорируется. Отловить его вы можете следующим образом:

from polog import log, LoggedError


@log
def error():
  return 4 / 0

try:
  error()
except LoggedError as e:
  # Поймал - выброси.
  pass

Будьте осторожны с этим! Если ваш стиль кодирования подразумевает проброс исключений на несколько уровней и их ловлю с указанием типа, данное поведение следует отключить. Делается это через настройки, вот так:

from polog import config


config.set(original_exceptions=True)

Декорируем классы

Помимо функций, объектом log вы можете декорировать также и целые классы. Все работает точно так же: можно указывать или не указывать все те же аргументы, использовать декоратор как со скобками, так и без.

При этом игнорируются дандер-методы класса (это те, чьи названия начинаются и заканчиваются символами "__").

Если не хотите логировать все методы класса, можете передать в декоратор список или кортеж с названиями нужных:

@log(methods=('important_method',), message='This class is also very important!!!')
class VeryImportantClass:
  def important_method(self):
    ...
  def not_important_method(self):
    ...
  ...

Не забывайте, что при наследовании вы получаете класс вместе с навешенным на его родителя логированием, и это логирование не знает, что работает уже не в оригинальном классе, а в наследнике. Если на наследника вы тоже навесите @log, логирование родителя у класса-ребенка заменится собственным. Но если вы этого не сделаете, логироваться он будет как родитель.

Перекрестное декорирование

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

Пример:

@log(level=6) # Сработает только этот декоратор.
@log(level=5) #\
@log(level=4) # |
@log(level=3) #  > А эти нет. Они знают, что их несколько на одной функции, и уступают место последнему.
@log(level=2) # |
@log(level=1) #/
def some_function(): # При каждом вызове этой функции лог будет записан только 1 раз.
  ...

Мы наложили на одну функцию 6 декораторов, однако реально сработает из них только тот, который выше всех. Это удобно в ситуациях, когда вам нужно временно изменить уровень логирования для какой-то функции. Не редактируйте старый декоратор, просто навесьте новый поверх него, и уберите, когда он перестанет быть нужен.

Также вы можете совмещать декорирование класса и его отдельных методов:

@log(level=3)
class SomeClass:
  @log(level=10)
  def some_method(self):
    ...

  def also_some_method(self):
    ...
  ...

У декоратора метода приоритет всегда выше, чем у декоратора класса, поэтому в примере some_method() окажется задекорирован только через декоратор метода, а остальные методы - через декоратор класса. Используйте это, когда вам нужно залогировать отдельные методы в классе как-то по-особенному.

Запрет логирования через декоратор @logging_is_forbidden

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

Импортируется @logging_is_forbidden так:

from polog import logging_is_forbidden

@logging_is_forbidden сработает при любом расположении среди декораторов логирования:

@log(level=5) # Этот декоратор не сработает.
@log(level=4) # И этот.
@log(level=3) # И этот.
@logging_is_forbidden
@log(level=2) # И вот этот.
@log(level=1) # И даже этот.
def some_function():
  ...

Также @logging_is_forbidden можно использовать для методов класса:

@log
class VeryImportantClass:
  def important_method(self):
    ...

  @logging_is_forbidden
  def not_important_method(self):
    ...
  ...

Иногда это может быть удобнее, чем прописывать "разрешенные" методы в самом декораторе класса. Например, когда в вашем классе много методов и строка с их перечислением получилась бы слишком огромной.

Имейте ввиду, что @logging_is_forbidden "узнает" функции по их id. Это значит, что, если вы задекорируете функцию каким-то сторонним декоратором после того, как она помечена в качестве нелогируемой, декораторы Polog будут относиться к ней как к незнакомой:

@log(level=2) # Этот декоратор сработает, так как не знает, что some_function() запрещено логировать, поскольку функция, вокруг которой он обернут, имеет другой id.
@other_decorator # Какой-то сторонний декоратор. Из-за него изменится первоначальный id функции some_function() и теперь для декораторов Polog это совершенно новая функция.
@logging_is_forbidden
@log(level=1) # Этот декоратор не сработает, т.к. сообщается с @logging_is_forbidden.
def some_function():
  ...

Поэтому декораторы Polog лучше всего располагать поверх прочих декораторов, которые вы используете. Исключение - регистрирующие декораторы, например роуты во фреймворках вроде Flask. Там синтаксис декораторов используется не для того, чтобы подменить оригинальную функцию, а для регистрации ее где-то. Для корректной работы регистрирующих декораторов, они должны быть размещены поверх всех прочих. То есть иерархия декораторов должны быть по следующей (чем больше номер - тем дальше от определения оригинальной функции): 1. обычные сторонние декораторы, 2. декораторы Polog, 3. регистрирующие декораторы.

Редактируем автоматические логи из задекорированных функций

Используя декораторы Polog, иногда вы можете столкнуться с необходимостью добавить или изменить какую-то информацию, которая логируется автоматически. В этом вам поможет функция message().

Пример работы:

from polog import log, message


@log(message='original message')
def some_function():
  message('new message')

В полученном логе поле 'message' будет заполнено первым аргументом функции message().

У объекта log есть метод, который делает то же самое. Вы можете применять его, чтобы не импортировать message() отдельно:

@log(message='original message')
def some_function():
  log.message('new message')

Также вы можете передавать в message() другие именованные аргументы:

• e или exception (Exception) - экземпляр исключения, которое вы хотите залогировать. Название и сообщение из него будут извлечены автоматически, однако метка success затронута не будет.
• success (bool) - метка успешности операции.
• level (str, int) - уровень лога.
• local_variables (str) - ожидается json с локальными переменными.

"Ручное" логирование

Отдельные важные события можно регистрировать вручную. Для этого нужно использовать объект log как обычную функцию. Отличие от метода message() в данном случае в том, что мы не редактируем автоматически созданную запись, а создаем новую при каждом вызове объекта log как функции.

Пример использования:

from polog import log


log('Very important message!!!')

Обратите внимание, что первым аргументом всегда идет строка. Ею заполняется поле message в получившейся записи.

Уровень логирования указывается так же, как при использовании объекта log в виде декоратора:

# Когда псевдонимы для уровней логирования прописаны по стандартной схеме.
log('Very important message!!!', level='ERROR')
# Ну или просто в виде числа.
log('Very important message!!!', level=40)

При желании, вы можете вызывать от объекта log методы, соответствующие названиям зарегистрированных ранее уровней логирования:

from polog import config, log
# Присваиваем уровню 100 имя "lol".
config.levels(lol=100)
# Регистрируем лог уровня "lol".
log.lol('kek')

Запись лога через метод "lol" в примере выше полностью идентична прямому вызову log() как функции, с указанием соответствующего уровня, то есть вот так:

log('kek', level='lol')

Впрочем, это работает в том числе и при использовании объекта log как декоратора, и вам уже, вероятно, знакомо.

Вы можете передать в log() функцию, в которой исполняется код:

def foo():
  log(function=foo)

Колонки function и module в этом случае заполнятся автоматически.

Также вы можете передать в log() экземпляр исключения:

try:
  var = 1 / 0
except ZeroDivisionError as e:
  log('I should probably stop dividing by zero.', exception=e)

Колонки exception_message и exception_type тогда тоже заполнятся автоматически. Флаг success будет установлен в значение False. Трейсбек и локальные переменные той функции, где произошла ошибка, заполнятся автоматически.

При желании, в качестве аргументов function и exception можно использовать и обычные строки, но тогда дополнительные поля не заполнятся сами как надо.

Также вы можете передавать в log() произвольные переменные, которые считаете нужным залогировать. Для этого нужно использовать функцию json_vars(), которая принимает любые аргументы и переводит их в стандартный json-формат:

from polog import log, json_vars


def bar(a, b, c, other=None):
  ...
  log(':D', function=bar, vars=json_vars(a, b, c, other=other))
  ...

Также вы можете автоматически получить все переменные в функции при помощи locals():

def bar(a, b, c, other=None):
  ...
  log(':D', function=bar, vars=json_vars(**locals()))
  ...

Добавляем собственные поля

Существует легкий способ расширить функциональность Polog - добавить в него собственные поля. Поле - это некая именованная сущность, которая извлекается из "сырых" данных при каждом логируемом событии. "Сырые" данные - это все то, что передается в обработчик.

Заполнение поля происходит в 3 этапа:

1. Извлечение данных. Из аргументов задекорированной функции и извлеченных переменных создается некое промежуточное представление. Этот этап выполняется в основном потоке.
2. Передача аргумента вместе со всеми прочими для записи в дочерние потоки.
3. Перед записью происходит получение финального строкового представления, которое используется всеми обработчиками.

Рассмотрим пример дополнительного поля, в которое будет извлекаться ip-адрес клиента из обработчика запроса Django. Сам обработчик запросов выглядит примерно вот так:

import datetime
from django.http import HttpResponse
from polog import log


@log
def current_datetime(request):
    now = datetime.datetime.now()
    html = "<html><body>It is now %s.</body></html>" % now
    return HttpResponse(html)

Чтобы ip извлекался из запроса автоматически, необходимо зарегистрировать в Polog extractor - функцию, которая получит на вход "сырые" аргументы функции и уже успевшие извлечься на момент вызова extractor'а прочие аргументы. На выходе extractor должен дать некий объект, который будет помещен в очередь для записи лога. Делается это примерно так:

from polog import config, field


def ip_extractor(args, **kwargs):
  request = args[0][0]
  ip = request.META.get('REMOTE_ADDR')
  return ip

config.add_fields(ip=field(ip_extractor))

Теперь при каждом логируемом событии в обработчик логов будет передаваться среди прочих аргумент под названием "ip", значением которого будет извлеченный из строки запроса ip-адрес. Как видите, в данном extractor'е нет никакой обработки ошибок. Их экранирование происходит в самом Polog. Если случится ошибка при извлечении конкретного поля - оно просто не извлечется, на запись прочих полей это никак не повлияет.

При необходимости, вы можете также указать функцию, ответственную за форматирование извлеченных данных в строку перед непосредственно записью:

def ip_converter(ip):
  return ip.replace('.', '-')

config.add_fields(ip=field(ip_extractor, converter=ip_converter))

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

Обработчики

Обработчик логов - это некая функция, которую Polog вызывает для каждого логируемого события. Их может быть несколько. Вы можете написать свой обработчик и зарегистрировать его в логгере. К примеру, он может слать логи в вашу любимую NoSQL базу данных, писать их в файловую систему, выводить в консоль, или отправлять вам в мессенджерах / соцсетях.

Сигнатура обработчика строго фиксирована, и при попытке зарегистрировать в качестве обработчика функцию неправильного формата - поднимется исключение. Вот пример правильной сигнатуры (имена аргументов совпадать не обязаны):

def handler(function_input_data, **fields):
  ...

Здесь function_input_data - это кортеж из двух элементов, соответственно *args и **kwargs задекорированной функции. Когда лог формируется не автоматически через декоратор, обоими элементами кортежа будет None. Если используете в своих обработчиках какие-то данные из function_input_data, будьте осторожны с изменяемыми типами данных - рискуете зааффектить работу исходной функции. Кроме того, учитывайте многопоточность Polog: ваш обработчик вызывается не из того же потока, где отработала задекорированная функция. Некоторые объекты (например, подключения к базам данных) от этого могут вести себя иначе. Лучше всего не использовать какие-либо данные из function_input_data без крайней необходимости и понимания того, что вы делаете.

**fields - это словарь с содержимым лога, уже собранным для обработчика движком polog. Набор полей полностью не фиксирован. Вот, какие поля в нем могут быть:

• level (int, обязательное) - уровень важности лога.
• auto (bool, обязательное) - метка, автоматический лог или ручной. Проставляется автоматически, вы не можете этим управлять.
• time (datetime.datetime, обязательное) - дата и время начала операции.
• service (str, обязательное) - название или идентификатор сервиса, из которого пишутся логи. Идея в том, что несколько разных сервисов могут отправлять логи в какое-то одно место, и вы должны иметь возможность их там различить. Имя сервиса по умолчанию - 'base'. Изменить его вы можете через настройки.
• success (str, не обязательное) - метка успешного завершения операции. При автоматическом логировании проставляется в значение True, если в задекорированной функции не произошло исключений. При ручном логировании вы можете проставить метку самостоятельно, либо она заполнится автоматически, если передадите в функцию log() объект исключения (False).
• function (str, не обязательное) - название функции, действие в которой мы логируем. При автоматическом логировании (которое происходит через декораторы), название функции извлекается из атрибута __name__ объекта функции. При ручном логировании вы можете передать в логгер как сам объект функции, чтобы из нее автоматически извлекся атрибут __name__, так и строку с названием функции. Рекомендуется предпочесть первый вариант, т.к. это снижает вероятность опечаток.
• module (str, не обязательное) - название модуля, в котором произошло событие. Автоматически извлекается из атрибута __module__ объекта функции.
• message (str, не обязательное) - произвольный текст, который вы можете приписать к каждой записи.
• exception_type (str, не обязательное) - тип исключения. Автоматические логи заполняют эту колонку самостоятельно, вручную - вам нужно передать в логгер объект исключения.
• exception_message (str, не обязательное) - сообщение, с которым вызывается исключение.
• traceback (str, не обязательное) - json со списком строк трейсбека. При ручном логировании данное поле заполняется автоматически при передаче в функцию log() экземпляра исключения.
• input_variables (str, не обязательное) - входные аргументы логируемой функции. Автоматически логируются в формате json. Стандартные для json типы данных указываются напрямую, остальные преобразуются в строку. Чтобы вы могли отличить преобразованный в строку объект от собственно строки, к каждой переменной указывается ее оригинальный тип данных из кода python. Для генерации подобных json'ов при ручном логировании рекомендуется использовать функцию json_vars(), куда можно передавать любые аргументы (позиционные и именные) и получать в результате стандартно оформленный json.
• local_variables (str, не обязательное) - локальные переменные функции. Извлекаются автоматически при логировании через декораторы, либо если вы передадите в функцию log() экземпляр исключения. Также представлены в виде json с указанием типов данных.
• result (str, не обязательное) - то, что вернула задекорированная логгером функция. Вы не можете заполнить это поле при ручном логировании.
• time_of_work (float, не обязательное) - время работы задекорированной логгером функции, в секундах. Проставляется автоматически. При ручном логировании вы не можете указать этот параметр.
• Прочие именованные поля, добавленные вручную. Вы можете дать им любые имена, кроме указанных выше.

Рассмотрим простейший обработчик:

from polog import config, log


def print_function_name(function_input_data, **fields):
  if 'function' in fields:
    print(fields['function'])
  else:
    print('is unknown!')

# Передаем ваш обработчик в Polog. В метод add_handlers() можно передать несколько функций через запятую.
config.add_handlers(print_function_name)
# В консоли появится сообщение из вашего обработчика.
log('hello!')

В данном примере мы зарегистрировали новый обработчик, передав его методу config.add_handlers(). Внутри Polog каждый обработчик сохраняется под определенным именем. Либо оно будет сгенерировано автоматически, как в примере выше, либо вы зададите его вручную, передавая свои обработчики в тот же метод в качестве именованных аргументов, вот так:

# В данном случае обработчик будет зарегистрирован под именем "handler_name".
config.add_handlers(handler_name=handler)

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

Получить словарь со всеми зарегистрированными обработчиками можно при помощи метода config.get_handlers():

all_handlers = config.get_handlers()
print(all_handlers)

Там вы заодно можете и подглядеть, какие имена были автоматически присвоены обработчикам, которые вы сами не потрудились как-то назвать. Также вы можете получить словарь с конкретными обработчиками, перечислив их по именам при вызове того же метода:

required_handlers = config.get_handlers('handler_name_1', 'handler_name_2')

Ну и наконец, удаление обработчиков:

config.delete_handlers('handler_name_1', 'handler_name_2')

Работает как по названиям, так и прямой передачей объекта обработчика. То есть можно делать как-то так:

config.add_handlers(handler)
# Обработчик добавлен...
config.delete_handlers(handler)
# ... и теперь удален.

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

Выводим логи в консоль или в файл, включаем ротацию

Наверное, самый популярный способ работы с логами - это их вывод в консоль или запись в файл. Разумеется, Polog так тоже умеет. Для этого необходимо подключить встроенный обработчик, вот так:

from polog import config, file_writer


config.add_handlers(file_writer())

В данном примере обработчик был инициализирован без аргументов, поэтому все необходимые настройки проставлены по умолчанию. В частности, способ вывода логов будет выбран - в консоль (поток stdout). Если вы хотите записывать логи в конкретный файл, передайте его имя первым неименованным аргументом:

config.add_handlers(file_writer('file.log'))

При необходимости, в настройках обработчика вы также можете включить ротацию логов. Выглядит это так:

config.add_handlers(file_writer('file.log', rotation='200 megabytes >> archive.log'))

Ротация - это перенос содержимого файла с логами в какой-то другой файл, а также очистка текущего файла. Выражение, управляющее ротацией, состоит из 2-х частей. Слева от ">>" находится условие, при котором происходит ротация, справа - путь к файлу, куда мы перемещаем логи из исходного файла. Имейте ввиду, что ротация будет производиться не в точно указанный файл. К имени файла, которое вы указали, будет автоматически добавлена временная метка. Это нужно, чтобы ранее ротированные логи не перезатирались новыми. Условий может быть несколько, перечислить их вы можете через запятую. Проверка всех условий происходит перед каждой записью новой строки лога. Если хотя бы одно из условий сработало, будет проведена ротация, после чего уже в очищенный файл с логами будет записана новая строка.

В настоящее время Polog "из коробки" работает только с одним видом условий:

• Размер файла с логами. Пример условия вы уже видели выше, это выражения вроде:

'200 megabytes'
'5 megabytes'
'5 gb'

Левая часть условия - всегда целое число, правая - обозначение размерности. Поддерживается следующий набор размерностей: byte, kilobyte, megabyte, gigabyte, terabyte и petabyte. Любая из них может быть написана также с буквой "s" на конце, например bytes. Также поддерживаются сокращения: b, kb, mb, gb, tb и pb. Кратность шага размерности - 1024. То есть 1 kb == 1024 b, 1 mb == 1024 kb и т. д.

Включаем оповещения по электронной почте

Еще один встроенных обработчиков Polog позволяет настроить отправку электронных писем по SMTP-протоколу. Вам это может пригодиться для быстрого реагирования на какие-то особо критичные события в вашем сервисе.

Подключается так:

from polog import config, SMTP_sender


# Адреса и пароль абсолютно случайны.
config.add_handlers(SMTP_sender('[e-mail]', 'JHjhhb87TY*Ny08z)', 'smtp.yandex.ru', '[e-mail]'))

SMTP_sender - это вызываемый класс. Обязательных аргументов для его инициализации 4: адрес, с которого мы посылаем письма, пароль от ящика, адрес сервера, к которому мы подключаемся, и адрес, куда мы посылаем письма.

Письма, которые будут сыпаться вам на почту, будут выглядеть примерно так:

Message from the Polog:

auto = True
module = __main__
function = do
time = 2020-09-22 20:31:45.712366
exception_message = division by zero
exception_type = ZeroDivisionError
success = False
traceback = [" File \"some_path\", line 46, in wrapper\n result = func(*args, **kwargs)\n"," File \"test.py\", line 23, in do\n return x \/ y\n"]
local_variables = {"args":[{"value":55,"type":"int"},{"value":77,"type":"int"}]}
time_of_work = 2.86102294921875e-06
level = 2
input_variables = {"args":[{"value":1,"type":"int"},{"value":0,"type":"int"}]}
service_name = base

При необходимости, вы можете настроить отправку писем более тонко. Для этого в конструктор класса нужно передать дополнительные именованные параметры. Вот их список:

• port (int) - номер порта в почтовом сервере, через который происходит отправка почты. По умолчанию 465 (обычно используется для шифрованного соединения).
• text_assembler (function) - альтернативная функция для генерации текста сообщений. Должна принимать в себя те же аргументы, которые обычно передаются в пользовательские обработчики Polog, и возвращать строковый объект.
• subject_assembler (function) - по аналогии с аргументом "text_assembler", альтернативная функция для генерации темы письма.
• only_errors (bool) - фильтр на отправку писем. В режиме False (то есть по умолчанию) через него проходят все события. В режиме True - только ошибки, т. е., если это не ошибка, письмо гарантированно отправлено не будет.
• filter (function) - дополнительный фильтр на отправку сообщений. По умолчанию он отсутствует, т. е. отправляются сообщения обо всех событиях, прошедших через фильтр "only_errors". Вы можете передать сюда свою функцию, которая должна принимать стандартный для расширений Polog набор аргументов, и возвращать bool. Возвращенное значение True из данной функции будет означать, что сообщение нужно отправлять, а False - что нет.
• alt (function) - функция, которая будет вызвана в случае, если отправка сообщения не удалась или запрещена фильтрами. Набор принимаемых аргументов, опять же, стандартный для обработчиков.
• is_html (bool) - флаг, является ли отправляемое содержимое HTML-документом. По умолчанию False. Влияет на заголовок письма.

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

Кроме того, опять же, из-за затратности процесса отправки, некоторые письма могут не успеть отправиться в случае экстренного завершения программы.

Пишем свой обработчик

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

Вот, как импортируется базовый класс:

from polog.handlers.abstract.base import BaseHandler

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

get_content(function_input_data, **fields)
do(content)

Метод get_content() должен принимать те же аргументы, что стандартный обработчик. Его задача - вернуть некий объект, промежуточное представление лога. К примеру, если речь идет об обработчике, который пишет логи в файл, это будет новая строка.

Метод do() принимает объект, полученный из get_content(), и непосредственно выполняет действие, которое должно быть произведено с логом. Обычно это либо отправка куда-то лога (на другую машину, или в какой-то сервис, например), либо его запись (в файл, базу данных или куда-то еще).

Вот пример суперпростого обработчика, который, однако, будет работать:

class StupidHandler(BaseHandler):
  def get_content(self, args, **kwargs):
    return str({**kwargs})

  def do(self, content):
    with open('stupid_file.lol', 'a') as file:
      file.write(content)

Все! Весь механизм работы обработчика уже реализован в базовом классе и вам не нужно его повторять.

Все немного усложнится, если инициализация вашего обработчика требует каких-то дополнительных аргументов. Тут вам придется переопределить метод __init__() базового класса:

class LessStupidHandler(BaseHandler):
  def __init__(self, some_data, only_errors=False, filter=None, alt=None):
    # Мы все-таки используем инициализацию объекта из базового класса, чтобы не переписывать часть с валидацией стандартных аргументов.
    super().__init__(only_errors=only_errors, filter=filter, alt=alt)
    self.some_data = some_data

  def get_content(self, args, **kwargs):
    ...

  def do(self, content):
    ...

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

class DefendedInputHandler(BaseHandler):
  # 1. Размещаем в теле класса словарь input_proves.
  input_proves = {
      'some_data': lambda x: isinstance(x, str),
  }

  def __init__(self, some_data, only_errors=False, filter=None, alt=None):
    super().__init__(only_errors=only_errors, filter=filter, alt=alt)
    # 2. Вызываем метод .do_input_proves().
    self.do_input_proves(some_data=some_data)
    self.some_data = some_data
  ...

Как видно на примере, для добавления валидации произвольных аргументов, необходимо сделать 2 вещи: 1. разместить в теле класса словарь под названием input_proves, в котором ключи - это названия аргументов, а значения - функции, которые должны принимать эти аргументы и возвращать bool'еаны, означающие, что конкретный аргумент прошел / не прошел проверку; 2. вызвать метод do_input_proves(), передав ему в качестве именованных аргументов все переменные, которые необходимо провалидировать.

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

Если вы считаете, что он может быть полезен кому-то еще, опубликуйте его на pypi.org! При этом не забудьте приложить к нему инструкцию, как им пользоваться. При наименовании пакетов рекомендуем соблюдать единый формат: {micro-description}_polog_handler, например color_console_polog_handler. Часть перед "_polog_handler" должна описывать механизм его работы или место назначения, куда отправляются логи, и ей не стоит быть больше 1-3 слов. Публикуя свой проект на github, вы также можете прописать ему тег polog, чтобы его можно было увидеть в соответствующем топике.

Общие советы про логирование

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

• Заведите для хранения логов отдельную машину. Она может быть одна для нескольких разных проектов или сервисов - главное, чтобы хранение логов физически не могло никак аффектить ваше основное приложение.

• Держите каждый класс в отдельном файле. Не держите "отдельно стоящих" функций в одном файле с классом. Помимо очевидного, что это делает вашу работу с проектом удобнее, это также устраняет возможность конфликта имен. Polog записывает название функции и модуля. Но если в модуле присутствуют 2 функции с одинаковыми названиями (например, в составе разных классов), вы не сможете их отличить, когда будете читать логи, и можете принять за одну функцию, которая почему-то ведет себя по-разному.

• Следите за конфиденциальностью данных, которые вы логируете. Скажем, если функция принимает в качестве аргумента пароль пользователя, ее не стоит логировать. Polog предоставляет удобные возможности для экранирования функций от логирования, например декоратор @logging_is_forbidden.

• Избегайте логирования функций, которые вызываются слишком часто. Обычно это функции с низким уровнем абстракции, лежащие в основе вашего проекта. Выберите уровень абстракции, на котором количество логов становится достаточно комфортным. Помните, что, поскольку запись логов в базу делается в отдельном потоке, то, что вы не чувствуете тормозов от записи логов, не означает, что логирование не ведется слишком интенсивно. Вы можете не замечать, пока Polog пишет по несколько гигабайт логов в минуту.

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

  Как пример, если вы пишете веб-приложение, у вас наверняка там будут какие-то классы или функции-обработчики для отдельных URL. Из них наверняка будут вызываться некие функции с бизнес-логикой, а оттуда - функции для работы с базой данных. Запускаете вы приложение в условной функции main(). В данном случае функции main() можно присвоить уровень 4, обработчикам запросов - 3, слою бизнес-логики - 2, ну и слою работы с БД - 1.

• Избегайте излишнего экранирования ошибок. Когда вы ловите исключения блоками try-except, в логирующие декораторы они могут не попасть. Поэтому полезно взять за правило каждое использование инструкции except сопровождать ручным логированием образовавшегося исключения.