Настройка логирования

Данный раздел описывает возможности настройки логирования в приложении. Логирование настраивается при помощи конфигов в формате json.

Настройки логирования называются профиль логирования. Количество профилей логирования не ограничено. Активный профиль логирования имеет значение флага active_flg=True.

Форматтер - определяет правила форматирования текстовых и json логов. Количество конфигураций форматтеров не ограничено.

Хендлер - определяет куда будет отправлен лог - в консоль (stdout) и/или в файл.

Логгер - позволяет определить уровень логирования (INFO | DEBUG etc.) и хендлер для компонента приложения. Если компонент в явном виде не определен в списке логгеров, то будет использован логгер root.
Для отключения хендлера логов компонента необходимо указать "handlers": []. В таком случае логов от компонента не будет.

JSON-конфиг

Пример конфигурации:

{
    "version": 1,
    "disable_existing_loggers": false,
    "formatters": {
      "text": {
        "()": "axiom.log_formatters.TextFormatter",
        "len_limit": -1
      },
      "text_limited": {
        "()": "axiom.log_formatters.TextFormatter",
        "len_limit": 16000
      },
      "json": {
        "()": "axiom.log_formatters.JSONFormatter",
        "fmt_keys": {},
        "len_limit": -1
      },
      "json_limited": {
        "()": "axiom.log_formatters.JSONFormatter",
        "fmt_keys": {},
        "len_limit": 16000
      },
      "json_full": {
        "()": "axiom.log_formatters.JSONFormatter",
        "fmt_keys": {},
        "len_limit": -1,
        "builtin_flds": true
      }
    },
    "handlers": {
      "stdout": {
        "class": "logging.StreamHandler",
        "level": "DEBUG",
        "formatter": "json_limited",
        "stream": "ext://sys.stdout"
      },
      "file": {
        "class": "logging.handlers.TimedRotatingFileHandler",
        "level": "DEBUG",
        "formatter": "json_full",
        "filename": "./axiom.log",
        "when": "midnight",
        "backupCount": 30
      }
    },
    "loggers": {
      "root": {
        "level": "DEBUG",
        "handlers": ["stdout", "file"]
      },
      "sqlalchemy": {
        "handlers": []
      },
      "sqlalchemy.engine": {
        "level": "INFO"
      },
      "fastapi": {
        "handlers": []
      },
      "uvicorn": {
        "handlers": []
      },
      "boto3": {
        "level": "ERROR",
        "handlers": []
      },
      "botocore": {
        "level": "ERROR",
        "handlers": []
      },
      "urllib3": {
        "level": "ERROR",
        "handlers": []
      },
      "httpx": {
        "level": "ERROR",
        "handlers": []
      },
      "requests": {
        "level": "ERROR",
        "handlers": []
      },
      "sentry_sdk": {
        "level": "ERROR",
        "handlers": []
      }
    }
}

Параметры, указанные в конфигурации:

version - Обязательный параметр с неизменяемым значением 1
disable_existing_loggers - отключение существующих логгеров, не входящих в конфигурацию (по умолчанию false)
formatters - Список форматтеров логгера
- text_* - Преднастроенный форматтер для вывода лога в текстовом формате, возможные параметры:
  - () - Класс форматтера, преднастроенный из axiom axiom.log_formatters.TextFormatter
  - len_limit - Ограничение длины лога
- json_* - Преднастроенный форматтер для вывода лога в формате json, возможные параметры:
  - () - Класс форматтера, преднастроенный из axiom axiom.log_formatters.JSONFormatter
  - fmt_keys - json с переименованием имен полей в логе
  - len_limit - Ограничение длины лога
  - builtin_flds - Вывод всех возможных полей лога (нужно для самого расширенного логирования)
handlers - Список хэндлеров логгера
- stdout - Вывод лога в stdout, параметры:
  - class - Класс хэндлера (по умолчанию встроенный logging.StreamHandler, подробнее см. документацию)
  - level - Уровень логирования
  - formatter - Форматтер из секции formatters
  - stream - Выбор стрима (по умолчанию ext://sys.stdout)
- file - Вывод лога в файл, параметры:
  - class - Класс хэндлера (по умолчанию встроенный logging.handlers.TimedRotatingFileHandler)
  - level - Уровень логирования
  - formatter - Форматтер из секции formatters
  - filename - Абсолютный путь до файла с логом
  - when - Когда осуществлять закрытие файла и открытие нового (по умолчанию midnight, подробнее о формате см. документацию)
  - backupCount - Количество файлов с логами (по умолчанию 30)
loggers - Список логгеров
- root - Основной логгер, где производится вся настройка, параметры:
  - level - Уровень логирования
  - handlers - Список хэндлеров из секции handlers
- sqlalchemy.engine - Логгер sqlalchemy, отвечает за вывод выполняемых запросов в лог
  - level - Уровень логирования. Для вывода основных запросов указать INFO.
- * - Все остальные логгеры
  - handlers - необходимо каждому из логгеров значение [], чтобы отключить встроенные хэндлеры.

Настройка API

В API существуют преднастроенные профили логирования для всех 5-ти уровней (DEBUG, INFO, WARNING, ERROR, CRITICAL).

Чтобы посмотреть все существующие конфигурации, необходимо вызвать метод /sys/logging_profiles.

Чтобы обновить конфигурацию, необходимо вызвать метод /sys/logging_profiles/{name} передав имя профиля и json-конфиг, в формате, описанном выше.

Отправка логов в fluent через UDP-plugin

Для подключения к fluent в конфигурацию необходимо добавить новый handler и подключить его к желаемым логгерам.

{
    ...
    "handlers": {
      "fluent": {
            "class": "fluent.handler.FluentHandler",
            "host": "localhost",
            "port": 24224,
            "tag": "test.logging",
            "formatter": "json_full",
            "level": "DEBUG"
      },
      ...
    },
    "loggers": {
      "root": {
        "level": "DEBUG",
        "handlers": ["stdout", "file", "fluent"]
      },
      ...
    },
    ...
}