Lancy Logger

Возможности

• Создание групп логов для разных частей проекта.
• Создание нескольких логов внутри каждой группы.
• Уровни TRACE, DEBUG, INFO, WARN, DANGER, ERROR, FATAL, SUCCESS.
• Включение и отключение записи отдельно для каждого уровня.
• Поиск по всем колонкам и фильтр по уровню.
• Быстрый просмотр последних записей больших файлов.
• Отображение количества записей и размера файла.
• Очистка содержимого без удаления самого лога.
• Скачивание исходного файла.
• Экспорт в xlsx, csv, txt, log.
• Просмотр, очистка и экспорт стандартных логов Bitrix/PHP.
• Настраиваемые пути к стандартным логам.
• Email-уведомления и административные уведомления Bitrix.
• Права на просмотр, создание и удаление.
• Запись удаления логов и групп в стандартный журнал событий Bitrix.
• Ограничение размера файлов и срока хранения записей.

Где открыть модуль

В административной части Bitrix откройте раздел:

Разработка -> Логирование

В меню находятся страницы:

• Список логов - группы и логи, созданные модулем.
• Стандартные логи - существующие файлы Bitrix и PHP.
• Документация - эта инструкция.

Настройки открываются на стандартной странице настроек модулей Bitrix:

Настройки -> Настройки продукта -> Настройки модулей -> Lancy: логирование

Группы и логи

Группа объединяет логи одной части проекта. Например:

• orders - заказы;
• import - импорт товаров;
• api - внешние интеграции;
• cron - агенты и фоновые задачи.

При создании группы укажите:

• Код - системное имя на латинице, например orders.
• Название - понятное название для административной части.
• Описание - необязательное пояснение.
• Сортировка - число, определяющее порядок в списке.

Внутри группы создаются отдельные логи. Например, группа orders может содержать:

• events - обычные события;
• errors - ошибки обработки;
• payments - платежи.

При создании лога укажите:

• Код - системное имя на латинице, например events.
• Название - название для административной части.
• Стандартные поля - базовые колонки модуля.
• Колонки - дополнительные данные конкретного процесса.

Если включены стандартные поля, создаются колонки:

• level - уровень записи;
• code - код лога;
• created_at - дата и время;
• created_by - ID пользователя или none.

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

order_id
request_id
status
message

На странице группы можно скачать исходный файл, изменить настройки лога, очистить записи или удалить лог полностью.

Просмотр и поиск

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

Доступны:

• поиск по всем колонкам;
• фильтр по уровню;
• цветные метки уровней;
• стандартная постраничная навигация Bitrix.

Количество загружаемых записей задается настройкой Количество последних строк для просмотра. По умолчанию открываются последние 5000 записей. Благодаря этому файл на сотни мегабайт не загружается в память целиком.

Поиск и фильтр на странице выполняются среди загруженных последних записей. Если нужно найти старую запись, временно увеличьте лимит или установите 0, но учитывайте размер файла и доступную память.

При первом открытии существующего большого CSV модуль подсчитывает записи и создает служебный кеш. Следующие открытия и переходы по страницам используют кеш и читают только небольшой участок с конца файла. Если файл изменен вручную, кеш обновляется автоматически.

Скачивание и очистка

В верхнем меню Скачать доступны варианты:

• Исходный файл - файл без преобразования;
• XLSX - таблица для Excel или LibreOffice Calc;
• CSV - универсальный табличный формат;
• TXT - простой текст;
• LOG - построчное представление.

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

Для создания настоящего XLSX на сервере должно быть доступно расширение PHP ZipArchive. Если расширение отсутствует, модуль возвращает CSV.

Действие Очистить лог удаляет все записи, но сохраняет сам лог, его код, колонки и настройки. После очистки код может продолжить записывать данные в тот же лог.

Действие Удалить удаляет и настройки, и файл. Для удаления и очистки требуется соответствующее право доступа.

Стандартные логи Bitrix и PHP

Раздел Стандартные логи предназначен для файлов, созданных самим Bitrix, PHP или кодом проекта.

Модуль автоматически учитывает:

• путь из константы LOG_FILENAME;
• путь из настройки PHP error_log;
• пути, указанные в настройках модуля.

По умолчанию предложены пути:

/bitrix/php_interface/debug.log
/bitrix/php_interface/error.log
/bitrix/php_interface/log.txt
/local/php_interface/debug.log
/local/php_interface/error.log
/local/php_interface/log.txt

В настройках можно указать другие файлы, по одному пути в строке. Поддерживаются пути от корня сайта и полные пути файловой системы.

/local/logs/exchange.log
/var/log/php/error.log

Файл появится в списке, если существует и доступен для чтения процессу PHP. Для очистки файл также должен быть доступен для записи.

Для стандартного лога доступны:

• количество строк, размер и дата изменения;
• просмотр последних строк;
• поиск по тексту;
• скачивание исходного файла;
• экспорт в поддерживаемые форматы;
• очистка без удаления файла.

Настройки

Email для уведомлений

Укажите адрес, на который должны приходить сообщения выбранных уровней. Отправитель берется из основной настройки Bitrix email_from. Если она не заполнена, используется адрес вида no-reply@домен-сайта.

Таблица уровней

Для каждого уровня доступны три параметра:

• Логировать - создавать записи этого уровня.
• Уведомления по почте - отправлять письмо после новой записи.
• Уведомления Bitrix - показывать административное уведомление.

Если в колонке Логировать выбрано Нет, запись не создается и уведомления не отправляются, даже если они включены в соседних колонках.

Назначение уровней:

• TRACE - максимально подробные шаги выполнения для сложной диагностики.
• DEBUG - отладочные данные интеграций, импортов и фоновых задач.
• INFO - обычные важные события, например создание заказа.
• WARN - отклонение, после которого процесс может продолжаться.
• DANGER - опасная ситуация, требующая быстрого внимания.
• ERROR - ошибка, из-за которой операция не выполнена.
• FATAL - критическая ошибка, после которой процесс не может продолжаться.
• SUCCESS - успешное завершение важного действия.

Ротация логов

• Максимальный размер лога в мегабайтах - старые записи удаляются, чтобы файл укладывался в лимит. Значение 0 отключает ограничение.
• Хранить последние записи логов, дней - удаляются записи старше заданного срока. Значение 0 отключает очистку по дате.

Ротация выполняется агентом Bitrix примерно один раз в сутки. Для очистки по дате лог должен содержать стандартное поле created_at.

Чтение логов

• Количество последних строк для просмотра - ограничивает объем данных на детальной странице. Значение 0 включает чтение всего файла.
• Пути к стандартным логам - список дополнительных файлов, по одному пути в строке.

Для рабочих проектов рекомендуется оставить ограничение строк. Значение 0 подходит только для небольших файлов или временной диагностики.

Уведомления

Уведомления создаются только после успешной записи в лог.

Уведомления Bitrix

Административное уведомление содержит короткий текст с кодом группы и лога. Для одной группы одновременно создается только одно уведомление. Пока оно существует, новые записи этой группы не добавляют новые уведомления и не занимают дополнительное место.

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

Email-уведомления

Письмо содержит уровень, код группы, код лога и записанные данные. Отправка выполняется стандартным почтовым транспортом Bitrix.

Если письмо не отправлено, модуль добавляет событие LANCY_LOGGER_EMAIL_ERROR в стандартный журнал событий Bitrix. В нем можно увидеть адрес и текст ошибки.

Если письма не приходят:

• проверьте адрес Email для уведомлений;
• проверьте, что для нужного уровня включены запись и email;
• проверьте основную настройку Bitrix email_from;
• найдите LANCY_LOGGER_EMAIL_ERROR в журнале событий;
• проверьте работу почты на сервере и папку со спамом.

Большое количество синхронных писем может замедлить процесс, который пишет лог. Включайте email для действительно важных уровней, например ERROR и FATAL.

Права доступа и журнал действий

Права задаются стандартным механизмом Bitrix:

• D - доступ запрещен;
• R - просмотр логов;
• W - просмотр, создание и изменение;
• X - просмотр, создание, изменение, очистка и удаление.

Администратор Bitrix всегда имеет полный доступ.

При удалении лога или группы модуль создает запись в стандартном журнале событий Bitrix. Запись содержит:

• ID пользователя;
• тип действия;
• код группы;
• код и название лога, если удален лог.

Для поиска используйте фильтр по модулю lancy.logger или типы событий:

LANCY_LOGGER_LOG_DELETED
LANCY_LOGGER_GROUP_DELETED

Очистка содержимого не считается удалением и не создает такую запись.

Запись из кода

Сначала создайте группу в административной части. Лог внутри существующей группы можно создать заранее или автоматически при первой записи.

Создать лог заранее

$logger = new \Lancy\Logger\Logger('orders');

$logger->register('events', [
    'order_id',
    'status',
    'message',
], true);

Здесь true включает стандартные поля.

Записать событие через builder

$log = new \Lancy\Logger\Logger('orders');

$log->info()
    ->findOrCreateCode('events')
    ->values([
        'order_id' => '1024',
        'status' => 'created',
        'message' => 'Заказ создан',
    ])
    ->log();

Если для INFO выбрано Логировать: Нет, вызов завершится без записи.

Короткая запись

$logger = new \Lancy\Logger\Logger();

$logger->error('orders', 'errors', 'Ошибка создания заказа', [
    'order_id' => '1024',
    'reason' => 'Не заполнен телефон',
]);

Сообщение попадет в колонку message, контекст - в колонку context.

Записать собственные значения

$logger = new \Lancy\Logger\Logger('api');

$logger->debug()
    ->findOrCreateCode('requests')
    ->value('method', 'POST')
    ->value('url', '/api/order/create')
    ->value('status', '200')
    ->log();

Доступные методы уровней:

$log->trace();
$log->debug();
$log->info();
$log->warn();
$log->danger();
$log->error();
$log->fatal();
$log->success();

Примеры для частых задач

Ошибка импорта

$log = new \Lancy\Logger\Logger('import');

$log->error()
    ->findOrCreateCode('products')
    ->values([
        'file' => 'products.csv',
        'row_number' => '128',
        'message' => 'Не найден раздел товара',
    ])
    ->log();

Успешная оплата

$log = new \Lancy\Logger\Logger('orders');

$log->success()
    ->findOrCreateCode('payments')
    ->values([
        'order_id' => '1024',
        'payment_id' => '890',
        'message' => 'Оплата получена',
    ])
    ->log();

Ошибка фоновой задачи

$log = new \Lancy\Logger\Logger('cron');

$log->fatal()
    ->findOrCreateCode('stocks')
    ->values([
        'task' => 'update_stocks',
        'message' => 'Не удалось получить остатки',
    ])
    ->log();

Рекомендации

• Используйте короткие коды групп и логов: orders, api, events, errors.
• Создавайте отдельные логи для независимых процессов.
• Не записывайте пароли, токены, данные банковских карт и другие секреты.
• Оставляйте ограничение последних строк включенным для больших файлов.
• Настройте ротацию до запуска интенсивного логирования.
• Используйте email для ERROR и FATAL, а не для каждого уровня.
• Проверяйте свободное место и права на каталог /local/lancy/logger/logs.
• Для очень высокой частоты событий используйте внешнюю систему сбора логов или очередь.
• Перед удалением группы скачайте нужные файлы: удаление необратимо.