Polog: логгер нового поколения

Логируйте красиво, удобно и без бойлерплейта. Избавьтесь от "мусора" в коде. Зацените фичи:

• Продвинутая функция log, которую можно использовать "как есть", а можно как контекстный менеджер или даже как декоратор для функций (в том числе корутинных) и классов.
• Просто настраивать, причем любые настройки можно менять "на лету" во время работы программы.
• Записи об ошибках не дублируются, когда исключение проходит через несколько декораторов логирования.
• Можно редактировать лог, записываемый декоратором, изнутри той функции, которую он оборачивает.
• Можно запретить логирование отдельных функций, навесив на них специальный декоратор.
• Ядро Polog поддерживает многопоточность, что иногда может заметно ускорить программу. В этом режиме запись лога становится неблокирующей операцией.
• Легко модифицировать. Можно писать собственные обработчики или добавлять собственную логику для автоматического заполнения полей лога.
• У логгера нет внешних зависимостей.
• Есть более 580 тестов, которые обеспечивают покрытие более чем на 96%. И стремление эти цифры еще увеличить.

Оглавление

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

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

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

$ pip install polog

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

from polog import config, file_writer


config.add_handlers(file_writer())

Теперь наши логи будут выводиться в консоль. При желании, в file_writer можно передать имя файла и тогда вывод будет происходить туда.

Теперь импортируем объект log и применим его к функции как декоратор:

from polog import log


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

sum(2, 2)

Результат:

[2022-10-28 16:02:55.988837] |    1    | SUCCESS |  AUTO  | where: __main__.sum() | time of work: 0.00001478 sec. | input variables: 2 (int), 2 (int) | result: 4 (int)

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

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

division(2, 0)

Результат:

[2022-10-29 00:23:20.699334] |    2    |  ERROR  |  AUTO  | where: __main__.division() | time of work: 0.00001097 sec. | input variables: 2 (int), 0 (int) | local variables: a = 2 (int), b = 0 (int) | exception: ZeroDivisionError("division by zero") | traceback: return a / b (".../main.py", line 9, in division)

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

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

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

OneOperation().operation(2, 0)

Результат:

[2022-10-29 00:24:53.348855] |    2    |  ERROR  |  AUTO  | where: __main__.OneOperation.division() | time of work: 0.0000031 sec. | input variables: <__main__.OneOperation object at 0x7fd1805a4100> (OneOperation), 2 (int), 0 (int) | local variables: self = <__main__.OneOperation object at 0x7fd1805a4100> (OneOperation), a = 2 (int), b = 0 (int) | exception: ZeroDivisionError("division by zero") | traceback: return a / b (".../main.py", line 10, in division)

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

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

В консоли:

[2022-10-28 16:11:27.704617] |    1    | UNKNOWN | MANUAL | "All right!" | where: ?
[2022-10-28 16:11:27.704997] |    2    |  ERROR  | MANUAL | "It's bad." | where: ? | exception: ValueError("Example of an exception.") | no traceback

Наконец, блок кода можно обернуть в логирующий контекстный менеджер:

with log("It's the context"):
  some_function()

Результат:

[2022-10-28 16:14:21.993514] |    1    | SUCCESS | MANUAL | "It's the context" | where: ? | time of work: 0.00001192 sec.

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

Зачем это нужно? О фреймворке

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

Обычно любой логгер, будь то Polog, logging или какой-то иной, содержит некий базовый набор компонентов:

1. Прежде всего, регистраторы логов. Чаще всего это какие-то функции, которые вызываются посреди основного кода программы. В Polog регистратор один - функция log, которую можно использовать одновременно и как обычную функцию, так и в виде декоратора (в том числе для классов) / контекстного менеджера.
2. Далее, поток событий необходимо отфильтровать. Для этого используются уровни логирования. На каждое событие ставится метка об уровне его важности (число, к которому может быть привязано отдельное имя), а глобально на уровне программы устанавливается планка, ниже которой события отбрасываются как несущественные.
3. На следующем шаге все оставшиеся события попадают в один компонент - движок. Задача движка - передать их на обработку специальным обработчикам и сделать немного другой, менее существенной работы.
4. Обработчики что-то делают с полученными сведениями. Типичный обработчик, к примеру, запишет информацию о событии в файл.

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

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.")

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

log('A normal event.')

Это важно не только из соображений красоты. Есть другая причина, экономия ментальных усилий. Вроде кажется не существенным, но знаете, почему большинство людей предпочитает дебажить и логировать через print? Потому что это просто, а им есть, о чем еще подумать, пока они пишут свою программу. Так вот, Polog - это даже проще, чем print.

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

Посмотрим опять на пример из logging:

def function(arg_1, arg_2):
  try:
    logging.info(f"begin of operations with {arg_1} and {arg_2}")
    operation(arg_1)
    operation_2(arg_2)
    logging.info(f"end of operations with {arg} and {arg_2}")
  except Exception as e:
    logging.error(f"ERROR of operations with {arg_1} and {arg_2}, {e}")
    raise

Мы видим здесь функцию, в которой "настоящей" логики всего пара строк. Остальное - логирование. Мы пишем логи когда операция начинается, когда кончается, и отдельно - в случае неудачи, для чего приходится еще городить блок try-except. Итого у нас на 2 строчки "настоящей" логики приходится еще 6 обеспечивающих логирование. Конечно, это утрированный пример и обычно в реальном коде все не так плохо. Чаще всего в функциях все же немного больше логики, обрамляемой логами, в результате чего соотношение строк "настоящего" кода и логирования становится чуть менее драматичным. Однако в целом неудобства все равно налицо:

1. Логирование заставляет писать больше кода, причем шаблонного, в котором легко опечататься. К слову, в примере допущена опечатка, которая ломает логирование, попробуйте ее найти.
2. Оно отвлекает от "настоящей" логики программы. Это происходит потому, что логи перемешаны с "настоящим" кодом, пишутся прямо посреди него. По сути с точки зрения логики программы логи являются не более чем визуальным мусором.

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

С Polog пример кода выше превращается в:

@log('Some message.')
def function(arg_1, arg_2):
  operation(arg_1)
  operation_2(arg_2)

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

Еще с Polog можно вот так:

def function(arg_1, arg_2):
  with log('Some message.'):
    operation(arg_1)
    operation_2(arg_2)

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

Третье важное отличие Polog - это отделение регистрирующей части от обработчиков. В logging регистраторы логов представляют из себя дерево, у которого есть свой root. К регистраторам привязаны обработчики, а вы пишете логи в регистраторы. Дерево регистраторов по сути разбросано по разным файлам вашей программы, в результате чего вы вынуждены повсюду создавать экземпляры регистраторов, если хотите иметь возможность специфицировать набор обработчиков для разных участков. В Polog тоже есть дерево, но это дерево обработчиков, а не регистраторов. За счет того, что объект регистратора всего один, появляется возможность установить log как built-in функцию, которую не нужно даже импортировать (это можно включить через настройки) в разных файлах программы.

Помимо перечисленного, Polog отличается от других логгеров еще множеством разных деталей, о них читайте ниже.

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

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

from polog import log

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

config.set(log_is_built_in=True)

log можно использовать для обычного ручного логирования:

log('plain text')

Или в качестве контекстного менеджера / декоратора для функций (в том числе корутинных) и классов:

                        | @log('plain text')   | @log('plain text')     | @log('plain text')
with log('plain text'): | def function():      | async def function():  | class SimpleClass:
   ...                  |    ...               |    ...                 |    ...

Функция сама понимает контекст, в котором она была вызвана! И подстраивает свое поведение соответственно.

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

                        | @log                 | @log                   | @log
with log:               | def function():      | async def function():  | class SimpleClass:
   ...                  |    ...               |    ...                 |    ...

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

config.levels(some_level=5)

Теперь это имя можно использовать при любом способе логирования:

# Обычная функция.
log.some_level('plain text')

# Контекстный менеджер.
with log.some_level:                   | with log.some_level('plain text'):
   ...                                 |    ...

# Декоратор функций.
@log.some_level                        | @log.some_level('plain text')
def function():                        | def function():
   ...                                 |    ...

# Декоратор корутинных функций.
@log.some_level                        | @log.some_level('plain text')
async def function():                  | async def function():
   ...                                 |    ...

# Декоратор классов.
@log.some_level                        | @log.some_level('plain text')
class SimpleClass:                     | class SimpleClass:
   ...                                 |    ...

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

log('plain text', level=5) # Будет работать в том числе через декораторы и контекстные менеджеры.
log('plain text', level='some_level')

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

Более подробно о специфических особенностях каждого из перечисленных выше способов регистрации логов читайте далее.

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

Важно: все приведенные здесь примеры ручного логирования могут работать немного странно, если запускать их через REPL. Это связано с особенностью реализации: при определении контекста, в котором вызывалась функция log, используется отслеживание жизненного цикла возвращаемого значения функции. Запись происходит при обнулении счетчика ссылок на этот объект. В REPL же последнее возвращенное значение сохраняется в переменной _, то есть счетчик ссылок обнулится и лог запишется, когда код в следующей строке перезапишет _.

Мы начнем с самого привычного способа записывать логи, когда сообщение просто передается в функцию log:

log('Very important message!!!')

Строка с сообщением заполняет поле message в получившейся записи.

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

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

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

from polog import config


config.levels(lol=100) # Присваиваем уровню 100 имя "lol".

log.lol('kek') # Регистрируем лог уровня "lol".

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

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

Вы можете передать в 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 можно использовать и обычные строки, но тогда дополнительные поля не заполнятся сами как надо.

Еще можно передать в логгер название или объект класса в виде аргумента class_ (с нижним подчеркиванием, поскольку слово "class" зарезервировано):

class Car:
  def wash(self):
    log('The washing begins.', class_=type(self))
    ...

И наконец, вы можете передавать в log() произвольные переменные, которые считаете нужным залогировать.

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

Контекстный менеджер

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

with log('Go out from the context!'):
  ...

Или даже так, это эквивалентно, просто записи будут без сообщений:

with log:
  ...

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

В реальных программах очень часто встречаются случаи, когда логгер вызывается внутри блока except (или хуже того, ошибки просто подавляются без всяких следов, даже в виде логов). С использованием стандартного logging это обычно выглядит примерно так:

try:
  some_function()
except SomeException:
  logging.exception('Error in some operation!')

При использовании контекстного менеджера Polog то же самое займет меньше строчек:

with log('Some operation!').suppress(SomeException):
  some_function()

Продемонстрированный здесь метод .suppress() работает очень похоже на suppress из стандартной библиотеки Python. Единственное отличие, если сюда не передать никаких аргументов, подавляться будут абсолютно все исключения:

with log('Some exception!').suppress():
  raise ValueError # Подавлено будет абсолютно любое исключение, включая это.

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

config.set(suppress_by_default=True)

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

with log('The message before change.') as context:
  context('The message after change.', some_variable='some text')

В примере выше мы изменили сообщение лога, а также добавили в него новое поле - some_variable.

При использовании log без скобок это тоже сработает:

with log as context:
  context('The message.', some_variable='some text')

Изменение лога внутри контекста доступно и при использовании метода .suppress():

with log('The message before change.').suppress() as context:
  context('The message after change.', some_variable='some text')
  raise ValueError

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

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

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

@log
def function():
  ...

... а можно и так, разницы нет:

@log()
def function():
  ...

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

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

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

def print_log(log_item): # Пример супер-примитивного обработчика. Не делайте так, придумайте что-то свое.
  print(log_item)

@log(handlers=[print_log])
def function():
  ...

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

from polog import field

@log(extra_fields={'kek': field(lambda log_item: 'kek')})
def function():
  ...

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

@log(extra_fields=[{'kek': field(lambda log_item: 'kek')}, ...])
def function():
  ...

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

@log(extra_engine_fields=[{'kek': field(lambda log_item: 'kek')}, ...])
def function():
  ...

Но имейте в виду, нужно это крайне редко.

Дедупликация исключений

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

@log
def function_3():
  raise ValueError

@log
def function_2():
  return function_3()

@log
def function_1():
  return function_2()

function_1()

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

config.set(deduplicate_errors=False)

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

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

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

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

@log('This class is also very important!!!', methods=('important_method',))
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() окажется задекорирован только через декоратор метода, а остальные методы - через декоратор класса. Используйте это, когда вам нужно залогировать отдельные методы в классе как-то по-особенному.

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

Некоторые вещи логировать опасно. К примеру, если вы пишете web-сервис, такими вещами могут быть пароли пользователей или токены для доступа к другим сервисам. Для таких случаев в Polog есть специальный декоратор - @unlog. Он делает так, что на защищенной им функции больше не будут срабатывать логирующие декораторы. Кроме того, по умолчанию там не будет работать и ручное логирование. Еще данный декоратор можно навесить на целый класс, и тогда все перечисленное будет работать на всех его методах. Ниже будут примеры.

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

from polog import unlog

Но если вам не хочется в лишний раз импортировать @unlog, можно воспользоваться уже импортированным объектом log, подставляя - перед ним:

@(-log) # Работает точно так же, как @unlog.
def some_function():
  ...

Простейший случай, "отмена" действия логирующего декоратора:

@unlog
@log(level=5) # Этот декоратор не сработает.
def some_function():
  ...

"Отмена" действия ручного логирования:

@unlog
def some_function():
  log('hello, kitty!') # Эта функция тоже не будет работать.

Немного более сложный случай. Мы навешиваем @unlog на функцию, из которой вызывается вторая функция, и вот на той второй функции логирование тоже перестанет работать, когда она вызывается из первой:

@log(level=5) # Это не сработает.
def some_function_2():
  log('hello, kitty!') # И это тоже.

@unlog
def some_function():
  some_function_2()

some_function()

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

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

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

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

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

Ну и на классы тоже можно навешивать @unlog:

@unlog
class NotImportantClass:
  def some_method(self):
    log('some boring message') # Не будет работать.

Выше было сказано, что по умолчанию @unlog отключает на обернутой им функции как декораторы логирования, так и ручные логи. Но это поведение можно изменить при помощи настройки full_unlog. По умолчанию она установлена в значение True, однако если изменить ее на False, то @unlog по-прежнему будет глушить декораторы логирования, но станет пропускать ручные вызовы логгера:

from polog import config


config.set(full_unlog=False)

@unlog
@log # Этот декоратор по-прежнему не сработает.
def some_function():
  log('hello, kitty!') # А это сработает!

some_function()

Кроме того, не обязательно изменять данную настройку глобально. @unlog можно вызвать со скобками, передав туда аргумент full:

@unlog(full=False)
@log # Это не будет работать.
def some_function():
  log('hello, kitty!') # А это будет.

Локальные аргументы имеют приоритет над выставленной глобально настройкой full_unlog.

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

1. Декоратор @unlog расположен поверх всех прочих декораторов логирования на данной функции, например вот так:

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

2. Он непосредственно прилегает к одному или нескольким логирующим декораторам, без прослойки в виде каких-то сторонних декораторов (не из Polog):

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

Однако! Если @unlog находится ниже другого логирующего декоратора и при этом их разделяет какой-то сторонний декоратор, защита может перестать работать:

@log(level=2) # Этот декоратор может сработать.
@other_decorator # Какой-то сторонний декоратор.
@unlog
@log(level=1) # Этот декоратор не сработает, т.к. сообщается с @unlog.
def some_function():
  ...

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

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

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

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

from polog import message


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

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

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

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

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

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

Умные ассерты

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

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

Выглядит это так:

from polog import ass


ass(False, "It's bad.") # Эквивалентно: assert False "It's bad."

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

from polog import config


config.set(smart_assert_politic='all')

Интеграция с logging

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

Прежде всего, Polog поддерживает прямой перехват событий из logging, причем это происходит по умолчанию:

import logging
from polog import config, file_writer

config.add_handlers(file_writer())

logging.warning('oops!')

Представленный выше код должен вывести что-то вроде:

[2015-10-21 18:52:12.856087] |   30    |  ERROR  | MANUAL | "oops!" | where: main.? | line_number: 6 | path_to_code: ".../main.py" | thread: "MainThread (8628192768)" | process: "MainProcess (10281)" | from_logging: True

Как видите, это не потребовало вообще никаких доработок или настроек на стороне logging. Но как это работает? В процессе участвуют две пункта настроек Polog, которые по умолчанию обе возведены в положение True: integration_with_logging и logging_off. В них нет никакой магии. Первая в значении True добавляет фильтр в root logger библиотеки logging, который перерегистрирует содержимое записи уже внутри Polog. То есть фильтр в данном случае используется по сути как коллбек. Вторая - это то значение, которое данный фильтр возвращает: True или False.

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

logger = logging.getLogger(__name__)

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

from polog.core.stores.settings.actions import from_logging_filter_to_polog

logger.addFilter(from_logging_filter_to_polog) # Не нравится, когда тычут в глаза камелкейсом? Переходите на Polog.

Еще один аспект синхронизации logging и Polog - имена уровней логирования. Дело в том, что Polog вам никак не предписывает, какие имена вы должны присваивать разным уровням. В logging же имена уже придуманы за вас:

Числовое значение	Имя
50	CRITICAL
40	ERROR
30	WARNING
20	INFO
10	DEBUG
0	NOTSET

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

from polog import log, config, file_writer

config.add_handlers(file_writer())
config.standard_levels()

log.error('My dog ate my homework :(') # Это сработает так, как вы ожидаете.

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

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

from polog import config

Все методы от него вызываются через точку, без вызова __init__, например вот так:

config.set(pool_size=5)

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

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

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

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

  max_queue_size (int) - максимальный размер очереди. Бесконечен в случае значения 0. Данный пункт актуален только в случае не нулевого значения pool_size.

  service_name (str) - имя сервиса. По умолчанию не задано, но вы можете передать сюда желаемое имя и оно будет отображаться во всех логах. Если вы используете микросервисную архитектуру, сюда рекомендуется пробрасывать уникальный идентификатор сервиса, к примеру, через переменные окружения.

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

  default_level (int, str) - уровень логирования, с которым по умолчанию логируются обычные события. По умолчанию он равен 1.

  default_error_level (int, str) - уровень логирования, с которым по умолчанию логируются ошибки. По умолчанию он равен 2-м.

  max_delay_before_exit (int, float) - задержка в секундах перед завершением программы для записи оставшихся логов. При завершении работы программы может произойти небольшая пауза, в течение которой будут записаны оставшиеся логи из очереди. Настройка изменяет максимальную продолжительность такой паузы, однако если все логи успели записаться быстрее, лишнего ожидания не произойдет. Также стоит учитывать, что при значении pool_size, равном нулю, манипуляция данной настройкой становится бессмысленной, поскольку при этом помещение логов в очередь перед записью не происходит.

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

  json_module (module) - модуль для обработки данных в формате json. Обязательно должен включать 2 функции: loads() и dumps(). Для ускорения работы рекомендуется передать сюда модуль из библиотеки ujson.

  time_quant (int, float) - продолжительность (в секундах) некоторых внутренних операций в Polog. Изменять не рекомендуется.

  fields_intersection (bool) - поведение при пересечении различных извлекаемых полей под одинаковым именем. Если fields_intersection установлено в значение True, то внутри движка может происходить перезапись полей, извлеченных ранее. В противном случае - нет.

  unknown_fields_in_handle_logs (bool) - можно ли передавать при ручном логировании функцией log() аргументы с неизвестными именами. По умолчанию можно (True).

  deduplicate_errors (bool) - режим дедупликации автоматических логов об исключениях. По умолчанию - True, то есть включен.

  log_is_built_in (bool) - устанавливаем функцию log() в качестве встроенной. По умолчанию - False, то есть данный режим выключен. Если включить, log() можно будет вызывать из любого места программы без дополнительного импорта, по аналогии, к примеру, со встроенной функцией print().

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

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

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

  integration_with_logging (bool) - интеграция с модулем logging из стандартной библиотеки. При значении True (по умолчанию) записи логов из logging копируются в Polog, а при False - нет. Привести данную настройку в False можно только при условии, что logging_off также False.

  logging_off (bool) - блокировка вывода всех логов через модуль logging. В значении True (по умолчанию) все записи в logging игнорируются, не передаются обработчикам. Этот механизм может работать только при условии, что настройка integration_with_logging находится также в положении True (сочетание, при котором logging_off и integration_with_logging находятся в положениях, соответственно, True и False, является невозможным). В значении False все записи будут игнорироваться в logging, однако за счет того, что настройка integration_with_logging стоит в положении True, они будут обрабатываться внутри Polog. То есть это работает по сути как чистый перехват всех сообщений. Они не доходят до адресатов (обработчиков) внутри системы logging, но обрабатываются внутри Polog.

  traceback_cutting (bool) - обрезание трейсбека при использовании декоратора для функций. В значении True (по умолчанию) из трейсбека вырезаются фрагменты, отражающие работу самого декоратора. То есть декоратор не должен как-либо воздействовать на трейсбек. Если отключить данный режим, трейсбек станет более длинным и менее информативным для большинства пользователей, однако более "честным".

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

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

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

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

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

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

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

• add_engine_fields(): регистрация новых извлекаемых полей, обрабатываемых внутри движка.

• delete_engine_fields(): удаление внутридвижковых извлекаемых полей.

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

• get_engine_fields(): получение словаря с извлекаемыми полями, которые отрабатывают внутри движка. По аналогии с get_in_place_fields(), если не передавать в метод ничего, вернет все такие поля, а если передать одно или несколько имен (в качестве неименованных аргументов), то вернет только их.

• get_all_fields(): получить словарь с извлекаемыми полями всех видов (то есть как отрабатывающих внутри движка, так и до). По аналогии с get_in_place_fields() и get_engine_fields(), если не передавать в метод ничего, вернет все такие поля, а если передать одно или несколько имен (в качестве неименованных аргументов), то вернет только их. В случае, если два разных экстрактора для извлечения вне движка и внутри него зарегистрированы под одинаковыми именами, данный метод учитывает значение настройки

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

Уровни логирования - это универсальный и удобный способ разделить все события на группы, и разбить эти группы на две части: одну мы логируем, а другую - нет. "Разделителем" служит глобальный уровень логирования, его мы устанавливаем для всей программы. Каждое событие также имеет пометку об уровне. Если уровень события больше, чем глобальный, или равен ему, оно будет записано, а иначе - проигнорировано. Вы можете не указывать при каждом вызове логгера уровень, которым будут помечаться отслеживаемые им события. В этом случае события будут помечаться уровнями по умолчанию. Для обычных событий уровнем по умолчанию является 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(default_error_level=50)

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

Для обычных событий тоже можно установить уровень по умолчанию:

config.set(default_level=10)

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

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.standard_levels()

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

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

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

from polog import log, config


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

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

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

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

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

Движки: синхронный и асинхронный

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

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

Примерами настроек, подразумевающих перезагрузку движка, являются pool_size и max_queue_size. Чтобы объяснить, почему при их изменении происходит перезагрузка движка, нужно рассказать, какие вообще бывают движки и как в одном из них (асинхронном) задействуются эти параметры.

Синхронный движок по своей сути очень примитивен. Это обычный объект, у которого есть метод, в который можно передать лог, и он передаст этот лог во все прикрепленные к нему обработчики. Вызов такого метода является блокирующей операцией, то есть ваша программа будет ждать, пока выполнится код всех обработчиков, и только после этого продолжит свое выполнение. За счет своей простоты такой обработчик порождает наименьший оверхед. Кроме того, в случае, к примеру, внезапного отключения питания компьютера, будет потеряна максимум одна запись лога - та, что на момент отключения была в работе. Какие тут минусы? При использовании обработчиков, которые, к примеру, передают логи куда-то по сети, сетевые задержки могут сильно тормозить вашу программу. Особенно это критично, если логгер используется внутри какого-нибудь нагруженного сервиса. Запросы на такой сервис могут приходить не равномерно, и сетевые операции обработчиков могут сильно снизить допустимую пиковую нагрузку.

Асинхронный движок в некоторых ситуациях (но далеко не всегда) может ускорить работу программы в целом. Его устройство уже значительно сложнее, чем у синхронного, и включает в себя несколько компонентов: очередь логов; объект, который кладет в нее логи; и несколько потоков с воркерами. Воркер - это некоторая функция, внутри которой запущен бесконечный цикл ожидания лога из очереди. Как только лог там появляется, кто-то из воркеров первым его забирает и далее с ним работает точно так же, как это делал бы обычный синхронный движок. В случае пиковой нагрузки, при которой воркеры не успевают обрабатывать поступающие логи, очередь растет, как бы "размазывая" во времени дополнительную нагрузку на сервер, которую создает сам логгер. Однако за все приходится платить, в данном случае - памятью и вычислительным оверхедом (который еще усугубляется наличием GIL). Чтобы выяснить, ускорят асинхронный движок и дополнительные потоки ваше приложение, или замедлят, нет другого способа, кроме нагрузочного тестирования, причем желательно проводить его в как можно более приближенных к реальности условиях. Реальное ускорение / замедление программы сильно зависит от характеристик железа, конкретного набора обработчиков, обрабатываемых данных и, возможно, от других факторов. Кроме того, вам нужно учитывать, что при работе асинхронного движка не гарантируется правильный порядок записи логов. Это связано с тем, что, хоть они и поступают в очередь практически в том же порядке, в каком происходили события вашей программы, время работы разных обработчиков может быть разным.

Настройки pool_size и max_queue_size влияют на выбор и характеристики движков. Установка pool_size в значение 0 (по умолчанию) приведет к загрузке синхронного движка, а любое значение больше 0 - асинхронного с соответствующим количеством потоков с воркерами. Пункт max_queue_size - это лимит числа логов в очереди для асинхронного движка. При значении 0 (то есть по умолчанию) лимит полностью отключается, с чем нужно быть осторожнее, поскольку очередь может стать местом утечки памяти в случае хронической нехватки мощности обработчикам. Если установить сюда любое положительное значение, при попытке положить в очередь новый лог, программа заблокируется до момента, пока кто-то из воркеров не заберет один лог из очереди.

При изменении любой из этих настроек происходит следующее:

1. Движок временно блокируется на запись логов. Функции, которые его вызывают, как бы подвиснут до момента, пока перезагрузка завершится.
2. Работа движка прекращается. В случае синхронного движка это означает, что возможно, просто записывается последний лог. Для асинхронного все сложнее. У него логи могут быть в двух разных местах. Во-первых, у него может быть не пустая очередь. То есть нужно дождаться, пока она опустеет. Во-вторых, каждый из воркеров может еще продолжать работу с последним из взятых логов. Поэтому, после опустения очереди, программа передает сигналы каждому воркеру, что после отработки текущего лога нужно завершиться. Воркер после обработки каждого лога проверяет, не был ли ему передан такой сигнал, и, если да - разрывает бесконечный цикл, не приступая к ожиданию следующего лога. В случае же, когда воркер на момент получения сигнала не был занят обработкой лога, а ожидал его из очереди, все немного сложнее. Само по себе ожидание не бесконечно. На самом деле ожидание - это смесь бесконечного цикла и блокировки потока. Поток блокируется на некоторый промежуток времени (в настройках он фигурирует как time_quant), после чего "просыпается" и проверяет, не поступало ли сообщение о завершении. Если да - выходит, нет - снова засыпает в ожидании лога.
3. Загружается новый движок. Причем решение, какой движок загружать и с какими параметрами, принимается уже на основе новых настроек.
4. Все функции, которые планировали записать лог, разблокируются и продолжают свою работу, даже не заметив, что движок "под капотом" сменился, а логгер, возможно, из синхронного стал асинхронным, или наоборот.

Так работает механизм защиты от потери логов при смене настроек.

Существует еще один сценарий, при котором происходит что-то похожее - это завершение работы программы. Polog при старте программы регистрирует через atexit специальный обработчик выхода. Внутри него должны выполняться шаги 1 и 2 из перечисленных выше, но с лимитом времени. Этот лимит вы можете корректировать, изменяя настройку max_delay_before_exit. Рекомендуем при манипуляции данной настройкой учитывать также max_queue_size, иначе возможна ситуация, когда очередь окажется слишком длинной, чтобы успеть "рассосаться" за отведенное время.

Об объекте лога

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

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

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

Данные можно получать по ключу:

>>> log_item['time']
datetime.datetime(2021, 10, 21, 11, 24, 51, 20811)
>>> log_item.get('time')
datetime.datetime(2021, 10, 21, 11, 24, 51, 20811)

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

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

Также у лога работают некоторые базовые методы словарей:

log_item.keys() # Коллекция ключей (названий полей) лога.
log_item.values() # Коллекция значений.
log_item.items() # Коллекция пар ключ-значение.

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

log_item.function_input_data.args
log_item.function_input_data.kwargs

log_item.function_input_data.args - это, соответственно, кортеж неименованных аргументов функции, а log_item.function_input_data.kwargs - словарь именованных. В случае, если лог зарегистрирован "вручную", log_item.function_input_data.args и log_item.function_input_data.kwargs будут ссылаться на None. При работе с переданными в функцию данными нужно соблюдать осторожность - существует риск, что вы их как-то измените, повлияв таким образом на работу программы. Без особой нужды лучше их вообще никак не использовать.

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

log_item.get_handlers()
# Вернется дерево обработчиков, привязанное к конкретному логу - по нему можно итерироваться.

Ну и последнее, у объекта лога перегружены операторы сравнения. Два таких объекта можно, пользуясь обычным синтаксисом сравнения в Python, сравнить между собой по полю time, где хранятся дата и время события. Это позволяет, к примеру, применять по отношению к коллекциям логов сортировки.

Добавляем извлекаемые поля

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

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

import datetime
from django.http import HttpResponse


@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(log_item):
  request = log_item.function_input_data.args[0]
  ip = request.META.get('REMOTE_ADDR')
  return ip

config.add_fields(ip=field(ip_extractor))

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

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

def ip_converter(ip):
  """Делаем так, чтобы ip-адрес указывался через дефис."""
  return ip.replace('.', '-')

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

В данном примере извлеченный extractor'ом ip-адрес прежде, чем попасть в лог, проходит через функцию, которую мы указали как converter.

Кроме того, вы можете указывать извлекаемые поля не для всей программы целиком, а для конкретного декоратора. На том же примере с обработчиком запросов Django это будет выглядеть так:

@log(extra_fields={'ip': field(ip_extractor)})
def current_datetime(request):
    now = datetime.datetime.now()
    html = "<html><body>It is now %s.</body></html>" % now
    return HttpResponse(html)

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

@log(extra_fields=[{'ip': field(ip_extractor)}, ...])
def current_datetime(request):
    ... # Речь не об этом троеточии.

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

Используйте config.add_engine_fields() вместо config.add_fields():

config.add_engine_fields(ip=field(ip_extractor))

И параметр extra_engine_fields вместо extra_fields для декораторов:

@log(extra_engine_fields={'ip': field(ip_extractor)})
def current_datetime(request):
    ...

Обработчики

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

Простейшая функция-обработчик может выглядеть примерно так:

from polog import config


def print_function_name(log_item):
  if 'function' in log_item:
    print(log_item['function'])
  else:
    print('is unknown!')

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

Каждый обработчик принимает 1 аргумент: объект лога.

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

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

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

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

all_handlers = config.get_handlers()
print(all_handlers)

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

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

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

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

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

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

Пространства имен и иерархия обработчиков

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

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

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

from polog import config


config.add_handlers(
  {
    'lol.kek': handler,
  }
)

Что здесь произошло?

1. Мы создали пустую ноду с именем lol.
2. Создали пустую ноду с именем kek и добавили ссылку на нее в ноду lol.
3. Положили в ноду lol.kek наш обработчик.

Добавим еще один обработчик:

config.add_handlers(
  {
    'lol.kek.cheburek': handler_2,
  }
)

Что изменилось? Ноды lol и kek уже существуют. Данной командой мы создали дочернюю к ноде kek ноду cheburek и положили в нее наш обработчик.

Теперь используем их:

@log(handlers=[handler_3, 'lol.kek'])
def function(a, b):
  return a * b

Что мы сделали? Мы создали для декоратора конкретной функции function() локальное пространство имен обработчиков и частично спроецировали туда глобальное пространство имен. Так туда попал уникальный обработчик handler_3, а также обработчики из глобального пространства имен - lol.kek и дочерний ему lol.kek.cheburek, итого 3 обработчика. Локальное пространство имен для конкретной функции переопределяет глобальное. Однако, если вы, уже после определения данной функции, добавите еще один обработчик по пути lol.kek.cheburek.peburek, он также отобразится в ее локальном пространстве, то есть обработчика станет четыре. Таким образом глобальное пространство имен частично проецируется на все локальные пространства, созданные для конкретных функций.

Выводим логи в консоль или в файл

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

from polog import config, file_writer


config.add_handlers(file_writer())

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

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

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

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

Ротация логов

Ротация - это перенос содержимого файла с логами в какой-то другой файл, а также очистка текущего файла.

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

from polog import file_writer


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

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

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

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

'200 megabytes'
'1 gigabyte'
'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 и т. д.

Операция ротации логов является потенциально опасной при конкурентном выполнении кода. Если 2 разных потока или процесса будут параллельно писать логи в один и тот же файл, а потом один из них решит провести ротацию, второй, который об этом ничего не знает, может записать свой лог между моментами, когда первый уже принял решение удалить файл, и когда он его уже фактически удалил. В результате одна или несколько строк могут потеряться безвозвратно. Такое поведение называется состоянием гонки. Чтобы избежать проблем с этим, в Polog доступны 2 типа блокировок: на уровне потока и на уровне файла.

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

Блокировка файла нужна для того же самого, но защищает уже на уровне процессов. Для ее работы автоматически создается еще один файл, название которого образовано из имени оригинального файла с логами + расширения .lock в конце. Файловая блокировка "под капотом" использует специфический системный вызов, который присутствует только в операционных системах семейства *NIX, поэтому, если вы используете Windows или иную специфическую ОС - данная блокировка, возможно, работать не будет.

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

handler = file_writer('file.log', rotation='200 megabytes >> archive', lock_type='thread+file')

В данном примере мы включили оба доступных типа блокировки.

Также можно включить только один:

# Только блокировка потока.
thread_locked_handler = file_writer('file.log', rotation='200 megabytes >> archive', lock_type='thread')
# Только блокировка файла.
file_locked_handler = file_writer('file.log', rotation='200 megabytes >> archive', lock_type='file')

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

handler = file_writer('file.log', rotation='200 megabytes >> archive', lock_type=None)

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

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

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

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

from polog import config, SMTP_sender


# Адреса и пароль абсолютно случайны.
config.add_handlers(SMTP_sender('from_me42@yandex.com', 'JHjhhb87TY*Ny08z)', 'smtp.yandex.ru', 'to_me@yandex.ru'))

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", альтернативная функция для генерации темы письма.
• is_html (bool) - флаг, является ли отправляемое содержимое HTML-документом. По умолчанию False. Влияет на заголовок письма.

Также данный обработчик принимает аргументы only_errors, filter и alt по аналогии с файловым. Делают они здесь то же самое, что и там.

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

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

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

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

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

from polog.handlers.abstract.base import BaseHandler

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

get_content(log_item)
do(content)

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

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

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

class StupidHandler(BaseHandler):
  def get_content(log_item):
    return str(log_item)

  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, log_item):
    ...

  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, в котором ключи - это названия аргументов, а значения - функции, которые должны принимать эти аргументы и возвращать булевые значения, означающие, что конкретный аргумент прошел / не прошел проверку; 2. вызвать метод do_input_proves(), передав ему в качестве именованных аргументов все переменные, которые необходимо провалидировать.

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

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

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

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

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

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

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

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

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

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