mxLogger - удобное логирование процессов в MODX Revolution

mxLogger — удобное логирование процессов в MODX Revolution 2.

Расставьте вызовы логгера с общими тэгами (например «purchase» и «cart») — и в менеджере найдёте все записи процесса по тэгу. В комплекте — готовый плагин, логирующий корзину и оформление заказа miniShop2, и автономный просмотрщик логов в обход MODX.

Возможности

Логирование с тэгами; у одной записи может быть несколько тэгов.
Группировка одной воронки через идентификатор процесса.
Автозахват источника вызова: класс, метод, файл, строка.
Для уровней «warning» и «error» — стэк вызовов и параметры (объекты сворачиваются в имя класса).
Автоматически пишутся пользователь, сессия, ip, время.
Фильтры записи: по пользователю, группе, сессии, куке.
Менеджерный грид с фильтрами, окном детали и кликом по значению для фильтрации.
Просмотр логов в обход MODX — CLI и WEB.

Требования к окружению

MODX Revolution 2.x (проверено на 2.8.5).
PHP 7.4 или новее.
MySQL 5.6+ / MariaDB на InnoDB — нужен FULLTEXT-индекс по тэгам.
Расширения PHP: PDO, mbstring, json.
Плагин логирования корзины/заказа работает только при установленном miniShop2.

Установка

Установите пакет через «Управление пакетами».
Создаются автоматически: таблица логов, namespace, меню «Компоненты → mxLogger», системные настройки, сниппет mxLogger и плагин mxLoggerMiniShop2.

Как добавлять логирование в свой код
После установки сервис зарегистрирован в extension_packages и доступен сразу как $modx->mxlogger — getService вызывать не нужно. Для краткости в примерах используем $mxl:

$mxl = $modx->mxlogger;

$mxl->debug('purchase', 'Открыта корзина');
$mxl->info('purchase', 'Корзина создана', ['cart_id' => $id]);
$mxl->warning('purchase', 'Низкий остаток', ['left' => 2]);
$mxl->error('purchase', 'Платёж отклонён', ['code' => 'declined']);

Несколько тэгов на одну запись:

$mxl->info(['cart', 'purchase'], 'Товар добавлен', ['product' => $pid]);

Процесс — один экземпляр воронки = один общий идентификатор:

$p = $mxl->process(['cart', 'purchase']); // идентификатор сгенерируется автоматически
$p->info('Старт оплаты', ['order' => 42]);
$p->error('Платёж отклонён', ['code' => 'declined']);
$uid = $p->getUid();                       // можно сохранить и продолжить позже

Принудительно снять полный стэк и параметры для конкретной записи:

$mxl->info('purchase', 'Создан заказ', $ctx, ['trace' => true]);

Если логируете через свою обёртку/фасад над сервисом — укажите её класс в опции skip_classes, чтобы «Источник» указывал на реальный вызывающий код, а не на обёртку (надёжнее жёсткого skip=N). Можно точное имя класса или префикс пространства имён со «\» на конце:

$mxl->info('payment', 'Платёж создан', $ctx, ['skip_classes' => ['My\\Payment\\Logger']]);

Из чанка или Fenom:

[[!mxLogger? &tags=`cart,purchase` &level=`info` &message=`Товар добавлен`]]

Тэги — только латиница и цифры в нижнем регистре, без пробелов; лишние символы вырезаются. Уровни: «debug», «info», «warning», «error».

Что пишется автоматически

Источник вызова — класс, метод, файл, строка. Движок пропускает кадры диспетчера событий, поэтому для плагинов показывает реальный метод (например msCartHandler::add), а не ~~служебный include~~.
Пользователь (id), сессия, ip, время.
Режим захвата трассировки — настройка mxlogger.capture_mode со значениями «off», «caller», «full», «auto» (по умолчанию: caller для info, full для warning и error).

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

mxlogger.filter_user — id или username через запятую;
mxlogger.filter_usergroup — id или имя группы;
mxlogger.filter_session — идентификатор(ы) сессии;
mxlogger.filter_cookie — «имя» либо «имя=значение».

Если задан хотя бы один фильтр — запись идёт только при совпадении.

События (для уведомлений и интеграций)
При каждой записи лога вызываются два системных события — на них можно вешать плагины (например уведомления):

«mxlOnBeforeLogSave» — ДО записи. В параметры передаются все поля будущей записи (tags, level, message, context, class, function, file, line, user_id, session_id, ip, createdon) и tags_list (массив тэгов). Плагин может отменить запись или изменить любое поле.
«mxlOnAfterLogSave» — ПОСЛЕ записи. Дополнительно передаётся id сохранённой записи. Удобно для нотификаций (письмо/мессенджер при error и т.п.).

Отменить запись из обработчика «mxlOnBeforeLogSave»:

$modx->event->returnedValues['prevent'] = true;

Изменить поле (например уровень) из «mxlOnBeforeLogSave»:

$modx->event->returnedValues['level'] = 'error';

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

Ротация (автоудаление старых логов)
Плагин mxLoggerRotate на событии OnMODXInit удаляет записи старше mxlogger.log_lifetime (по умолчанию 604800 секунд = неделя; 0 — не удалять). Реальная чистка выполняется не на каждом запросе, а не чаще раза в mxlogger.rotate_interval секунд (по умолчанию 3600 = раз в час). Удаление идёт порциями с ограничением за один проход, чтобы большой объём не нагружал сайт — остаток дочищается на следующих запусках.

Доступ к логам в обход MODX
Если MODX не загружается, логи можно смотреть скриптом по пути assets/components/mxlogger/standalone.php — он не запускает MODX, а читает таблицу напрямую через PDO (параметры БД берёт из core/config/config.inc.php).

CLI — по SSH, без ключа. Запускайте интерпретатором PHP 7.4, например:

php assets/components/mxlogger/standalone.php limit=20

Параметры (одинаковы для CLI и WEB): tag, level, process, ident, q, since, until, limit, id, full, color. Примеры:

tag=cart — по тэгу;
level=error — по уровню;
process=ms_xxxx — вся воронка процесса;
ident=admin — по пользователю, сессии или ip;
q=текст — поиск по сообщению, источнику, файлу;
since=«2026-06-01 10:00» и until=«2026-06-01 18:00» — диапазон дат;
limit=50 — число строк (по умолчанию 100, максимум 2000);
id=255 — показать одну запись целиком (context и trace);
full=1 — не усекать context/trace; color=1 или color=0 — форс цвета.

Список выводится таблицей. Чтобы развернуть запись — возьмите её номер из колонки ID и добавьте параметр id с этим номером.

WEB — нужен ключ, иначе 403. Откройте в браузере адрес скрипта с параметром key и, при необходимости, фильтрами, например: …/assets/components/mxlogger/standalone.php?key=ВАШ_КЛЮЧ&tag=cart&level=error

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

Файлом: создайте файл по пути core/components/mxlogger/standalone.key и впишите одну строку — ваш секрет. Сгенерировать секрет можно командой:
```
openssl rand -hex 20
```
Каталог core не отдаётся вебом, поэтому ключ снаружи не прочитать.
Переменной окружения MXLOGGER_TOKEN — предпочтительнее, ключ не светится в URL и логах сервера.

После этого открывайте адрес скрипта с параметром key. Чтобы выключить веб-доступ — удалите файл ключа (CLI продолжит работать). Чтобы сменить ключ — перезапишите файл новым значением.

Ссылка с ключом = доступ к логам (там сессии, ip, контекст). Не публикуйте её и передавайте только по защищённым каналам.

Если повреждён и сам файл core/config/config.inc.php — параметры БД можно задать переменными окружения MXLOGGER_DSN, MXLOGGER_DB_USER, MXLOGGER_DB_PASS, MXLOGGER_TABLE_PREFIX.

Системные настройки

mxlogger.enabled — глобальный выключатель записи;
mxlogger.min_level — минимальный уровень;
mxlogger.capture_mode, mxlogger.trace_limit, mxlogger.args_max_depth, mxlogger.args_max_string, mxlogger.args_max_items — захват трассировки;
mxlogger.tag_filter_mode — значения «auto», «fulltext», «like»;
mxlogger.log_lifetime — срок хранения в секундах (0 — не удалять).