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

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

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

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

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

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

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

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

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

Базовая конфигурация может содержать форматтеры, обработчики, логгеры и настройки корневого логгера. Пример минимальной конфигурации по умолчанию (текстовый формат вывода в 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       | Произошла серьёзная ошибка. Приложение может завершить работу или перестать функционировать корректно                     |

!!! Note "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 → Описание параметров](https://webim.ru/kb/devops/logging-configuration-for-chat-backend.html#cb-params)

---

Источник: https://webim.ru/kb/devops/logging-configuration-for-admin-backend.html