Логирование в Chat Backend

Основная информация

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

Для настройки системы логирования в Chat Backend используется конфигурационный файл logging.json. Он позволяет детально определить, как будут обрабатываться и форматироваться сообщения журнала, а также куда они будут отправляться. Также с его помощью можно настроить раздельное логирование - способ, который предполагает разделение логов по уровням, модулям и форматам. Это может облегчить анализ логов.

logging.json имеет структуру конфигурационного файла стандартного python-модуля logging. Это означает, что его формат и содержимое соответствуют принятым в этом модуле стандартам.

Файл logging.json позволяет:

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

Конфигурация логирования

В Chat Backend предусмотрено два способа получения файла конфигурации logging.json:

1. `Параметр запуска`: можно передать конфигурацию через параметр запуска `--logging_config`, указав путь к файлу:

  ```
  --logging_config=src/configs/logging.json
  ```

1. `По умолчанию`: если параметр запуска не указан, система автоматически использует файл конфигурации, который находится по пути `/opt/webim/envs/<имя окружения>/configs/`.

N.B

Файл logging.json уже входит в состав дистрибутива Chat Backend и будет автоматически найден и использован системой при запуске, если параметр запуска не указан.

Использование Tornado

В Chat Backend используется фреймворк Tornado, который также поддерживает собственное логирование. Tornado логирует запросы и ошибки, что позволяет лучше отслеживать и диагностировать работу сервера. Для интеграции логирования Tornado с общей системой логирования в logging.json добавляются соответствующие настройки логгеров.

Пример настройки логирования Tornado:

{
    "loggers": {
        "tornado.access": {
            "level": "INFO"
        },
        "tornado.application": {
            "level": "ERROR"
        },
        "tornado.general": {
            "level": "ERROR"
        }
    }
}

Базовые настройки

Файл logging.json содержит следующие базовые настройки:

Логирование на стандартный поток ошибок (stderr)
Уровень логирования для корневого логгера установлен на WARNING
Специфичные логгеры также могут иметь свои уровни логирования

Пример базовой конфигурации:

{
  "version": 1,
  "formatters": {
      "default_text": {
          "style": "{",
          "format": "[{levelname[0]} {asctime} {module}:{lineno}] {message}",
          "datefmt": "%y%m%d %H:%M:%S %z"
      }
  },
  "handlers": {
      "stderr": {
          "class": "logging.StreamHandler",
          "formatter": "default_text",
          "stream": "ext://sys.stderr"
      }
  },
  "root": {
      "handlers": ["stderr"],
      "level": "WARNING"
  },
  "loggers": {
      "webim": {
          "level": "INFO"
      },
      "clickhouse_driver.connection": {
          "level": "ERROR"
      }
  }
}

Параметры логирования при запуске Chat Backend

При запуске Chat Backend можно указать параметры логирования через командную строку. Один из таких параметров — --logging_config, который позволяет указать путь к файлу конфигурации logging.json.

Пример:

python main.py --logging_config=src/configs/logging.json

Направление логов в файл, stderr, systemd и другие места

Для направления логов в разные места (файл, stderr, systemd и т.д.) используются различные обработчики (handlers) в конфигурации logging.json.

Для логирования в файл используется FileHandler:

{
    "handlers": {
        "file_handler": {
            "class": "logging.FileHandler",
            "formatter": "default_text",
            "filename": "/var/log/chat_backend.log"
        }
    },
    "root": {
        "handlers": ["file_handler"],
        "level": "WARNING"
    }
}

Для логирования в стандартный поток ошибок (stderr) используется StreamHandler с параметром stream:

{
    "handlers": {
        "stderr": {
            "class": "logging.StreamHandler",
            "formatter": "default_text",
            "stream": "ext://sys.stderr"
        }
    },
    "root": {
        "handlers": ["stderr"],
        "level": "WARNING"
    }
}

Для логирования в systemd можно использовать SysLogHandler:

{
    "handlers": {
        "syslog": {
            "class": "logging.handlers.SysLogHandler",
            "formatter": "default_text",
            "address": "/dev/log"
        }
    },
    "root": {
        "handlers": ["syslog"],
        "level": "WARNING"
    }
}

Правила ротации логов

Для ротации логов используются RotatingFileHandler или TimedRotatingFileHandler.

Ротация по размеру файла

Использование RotatingFileHandler позволяет задавать максимальный размер файла и количество сохраняемых старых логов:

{
    "handlers": {
        "rotating_file_handler": {
            "class": "logging.handlers.RotatingFileHandler",
            "formatter": "default_text",
            "filename": "/var/log/chat_backend.log",
            "maxBytes": 10485760,
            "backupCount": 5
        }
    },
    "root": {
        "handlers": ["rotating_file_handler"],
        "level": "WARNING"
    }
}

Ротация по времени

Использование TimedRotatingFileHandler позволяет задавать интервал времени для ротации логов:

{
    "handlers": {
        "timed_rotating_file_handler": {
            "class": "logging.handlers.TimedRotatingFileHandler",
            "formatter": "default_text",
            "filename": "/var/log/chat_backend.log",
            "when": "midnight",
            "interval": 1,
            "backupCount": 7
        }
    },
    "root": {
        "handlers": ["timed_rotating_file_handler"],
        "level": "WARNING"
    }
}

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

Уровень	Значение	Описание
Status	777	Предоставляет информацию о статусе сервера и загрузке параметров лоогирования
Debug	10	Этот уровень предоставляет подробную информацию, полезную только при диагностике проблем
Info	20	Выводит в логах информационные сообщения о работе сервиса, например, об отправке сообщения или запросе к внутреннему API
Warning	30	Указывает на то, что произошло что-то неожиданное или проблема может возникнуть в ближайшем будущем
Error	40	Произошла ошибка, приложение не смогло выполнить некоторую функцию
Fatal	50	Произошла серьёзная ошибка. Приложение может завершить работу или перестать функционировать корректно

N.B.

При логировании высокого уровня будут также выводиться логи всех низлежащих уровней. Например, для уровня WARNING это будут ERROR и FATAL, для INFO - WARNING, ERROR и FATAL, и так далее.

Полезные настройки логгеров

* `INFO` для `sqlalchemy.engine` позволит вывести в лог все SQL-запросы к базе данных

* `INFO` для `tornado.access` может использоваться для вывода в лог информации о входящих HTTP-запросах.

API для управления уровнем логирования

Для управления уровнем логирования в режиме реального времени предусмотрен REST API.

Запрос для установки уровня логирования:

GET /l/a/monitor/set-log-level

Параметры запроса:

name: Название логгера.
level: Минимальный уровень логирования.
current_node_only: Применить только к текущему узлу (true/false).

Пример запроса:

GET /l/a/monitor/set-log-level?name=sqlalchemy.engine&current_node_only=false&level=info

Формат конфигурационного файла `logging.json`

{
    "version": 1,
    "formatters":
    {
        "default_text":
        {
            "style": "{",
            "format": "[{levelname[0]} {asctime} {module}:{lineno}] {message}",
            "datefmt": "%y%m%d %H:%M:%S %z"
        }
    },
    "handlers":
    {
        "stderr":
        {
            "class": "logging.StreamHandler",
            "formatter": "default_text",
            "stream": "ext://sys.stderr"
        }
    },
    "root":
    {
        "handlers": ["stderr"],
        "level": "WARNING"
    },
    "loggers":
    {
        "webim":
        {
            "level": "INFO"
        },
        "clickhouse_driver.connection":
        {
            "level": "ERROR"
        }
    }
}

Описание параметров

Параметр	Описание
`version`	Версия схемы конфигурации логирования
`formatters`	Определяет форматирование лог-сообщений
`formatters.default_text.style`	Вариант оформления логов
`formatters.default_text.format`	Формат строки лог-сообщения
`formatters.default_text.datefmt`	Формат даты и времени в логах
`handlers`	Определяет обработчики логов
`handlers.stderr.class`	Класс обработчика, который выводит логи в стандартный поток ошибок
`handlers.stderr.formatter`	Форматтер, используемый для этого обработчика
`handlers.stderr.stream`	Поток вывода
`root`	Настройки корневого логгера
`root.handlers`	Обработчики, используемые корневым логгером
`root.level`	Уровень логирования для корневого логгера
`loggers`	Настройки для отдельных логгеров
`loggers.webim.level`	Уровень логирования для логгера `webim`
`loggers.clickhouse_driver.connection.level`	Уровень логирования для логгера `clickhouse_driver.connection`, логирование содержит информацию о соединении с базой ClickHouse посредством драйвера

Описание параметров для `formatter`

Параметр	Описание	Пример
`levelname`	Уровень логирования	`DEBUG`, `INFO`, `WARNING`
`asctime`	Время создания записи лога	`2023-06-25 14:56:59,123`
`module`	Имя модуля (часть имени файла без расширения)	`example`
`lineno`	Номер строки в исходном коде, из которой были вызвано логи	`42`
`message`	Сообщение журнала	`Something happened`
`created`	Время создания записи лога (в секундах с начала эпохи - 1970-01-01 00:00:00)	`1624624619.123`
`filename`	Имя файла исходного кода, из которого было вызвано логирование	`example.py`
`funcName`	Имя функции, из которой было вызвано логирование	`my_function`
`levelno`	Числовое значение уровня логирования	`10`, `20`, `30`
`msecs`	Миллисекунды времени создания записи логирования	`123`
`name`	Имя логгера, который создал запись	`root`, `my_logger`
`pathname`	Полный путь к файлу исходного кода, из которого было вызвано логирование	`/path/to/example.py`
`process`	Идентификатор процесса (PID)	`12345`
`processName`	Имя процесса	`MainProcess`
`relativeCreated`	Время, прошедшее с момента запуска логирования (в миллисекундах)	`1234.567`
`thread`	Идентификатор потока	`140736987180032`
`threadName`	Имя потока	`MainThread`

Возможные спецификаторы параметра `datefmt`

Спецификатор	Описание	Пример
`%Y`	Полный год	`2024`
`%y`	Последние две цифры года	`24`
`%m`	Месяц (01-12)	`06`
`%d`	День месяца (01-31)	`25`
`%H`	Часы (00-23)	`14`
`%I`	Часы (01-12)	`02`
`%p`	AM или PM	`PM`
`%M`	Минуты (00-59)	`56`
`%S`	Секунды (00-59)	`59`
`%f`	Микросекунды (000000-999999)	`123456`
`%z`	Часовой пояс (смещение UTC)	`+0200`
`%Z`	Название часового пояса	`CEST`
`%j`	День года (001-366)	`176`
`%U`	Номер недели года (воскресенье как первый день недели)	`25`
`%W`	Номер недели года (понедельник как первый день недели)	`25`
`%c`	Полная дата и время	`Tue Jun 25 14:56:59 2024`
`%x`	Дата	`06/25/24`
`%X`	Время	`14:56:59`

Возможные параметры для `class`

Класс	Описание	Категория
`StreamHandler`	Логирование в поток (stdout, stderr)	Handlers
`FileHandler`	Логирование в файл	Handlers
`RotatingFileHandler`	Логирование в файл с ротацией по размеру	Handlers
`TimedRotatingFileHandler`	Логирование в файл с ротацией по времени	Handlers
`SocketHandler`	Логирование через сокет	Handlers
`DatagramHandler`	Логирование через UDP	Handlers
`SysLogHandler`	Логирование на syslog сервер	Handlers
`SMTPHandler`	Логирование через email	Handlers
`NTEventLogHandler`	Логирование в журнал событий Windows	Handlers
`MemoryHandler`	Буферизация логи в памяти	Handlers
`HTTPHandler`	Логирование на HTTP сервер	Handlers
`QueueHandler`	Логирование в очередь	Handlers
`Formatter`	Форматирование записей логи	Formatters
`Filter`	Фильтрация записей логи	Filters

Описание параметров для `stream`

Поток	Описание
`ext://sys.stdout`	Стандартный поток вывода
`ext://sys.stderr	Стандартный поток ошибок