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

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

Логирование — это фиксация и структурирование информации о работе Admin Backend в логах с возможностью быстрого анализа и аудита. Начиная с версии 10.8, в Admin Backend поддерживается чтение базовой конфигурации логгера из файла logging.json в корне приложения, а также подключение дополнительного внешнего файла конфигурации через аргумент запуска --logging-config.

Важно

Для Chat Backend и Admin Backend используются разные файлы конфигурации. Не указывайте один и тот же путь для обоих приложений.

Конфигурация по умолчанию

При старте Admin Backend выполняются следующие шаги:

1. Загружается конфигурация из файла logging.json, расположенного в корне приложения Admin Backend..

2. Если указан аргумент --logging-config="<путь к файлу>", то настройки из указанного файла сливаются с базовой конфигурацией.

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

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

{
  "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" }
  }
}

Внешний файл конфигурации (--logging-config)

Чтобы дополнить или переопределить базовую конфигурацию, передайте путь к дополнительному файлу:

python main.py --logging-config=/opt/webim/admin_backend/admin_backend_logging.json

Как работает слияние конфигураций

• Исходной точкой служит logging.json из корня приложения Admin Backend.

• Файл из --logging-config применяется поверх:

• словари объединяются по ключам (значения из внешнего файла имеют приоритет);

• скалярные значения и строки полностью перекрывают базовые;

• списки трактуются как целиком заданные внешним файлом (замена списка), если одноименный ключ присутствует во внешнем файле.

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

Пример:

Ниже — готовый вариант admin_backend_logging.json (его можно указать в --logging-config):

{
  "version": 1,
  "formatters": {
    "json": {
      "()": "pythonjsonlogger.jsonlogger.JsonFormatter",
      "format": "[%(levelname)s[0] %(asctime) %(module)s:%(lineno)s] %(message)s",
      "datefmt": "%y%m%d %H:%M:%S %z"
    }
  },
  "handlers": {
    "json": {
      "class": "logging.StreamHandler",
      "formatter": "json"
    }
  },
  "root": {
    "level": "DEBUG",
    "handlers": ["json"]
  }
}

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

Параметры запуска Admin Backend.

С версии 10.8 параметр запуска --log-level удален.

Вместо него используйте

--logging-config="<путь к файлу конфигурации логов>"

для подключения внешнего файла и настройки уровней/форматирования через конфигурацию.

Примеры

Простой запуск с базовой конфигурацией из logging.json в корне Admin Backend.:

python main.py

Запуск с добавлением JSON-форматирования:

python main.py --logging-config=/opt/webim/admin_backend/admin_backend_logging.json

Обработчики и ротация логов

Нужное направление вывода настраивается обработчиками (handlers) в конфиге:

• StreamHandler — вывод в stdout/stderr.
• FileHandler — запись в файл.
• RotatingFileHandler — ротация по размеру.
• TimedRotatingFileHandler — ротация по времени.
• SysLogHandler — вывод в systemd/journald через /dev/log.

Примеры фрагментов:

Вывод в файл:

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

Ротация по размеру:

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

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

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

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

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

N.B.

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

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

Зависимость python-json-logger

Для использования JSON‑форматирования требуется пакет:

pip install python-json-logger

В дистрибутиве Webim начиная с 10.8 пакет включен в зависимости Admin Backend. При самостоятельной установке убедитесь, что пакет присутствует в окружении, где запускается Admin Backend.

См. также

Справочник по параметрам конфигурации:
Логирование для Chat Backend → Описание параметров

---

Последнее обновление страницы: 5 мая 2026 г.