Логирование в 1С-Битрикс: полное руководство для разработчика

Отладка и мониторинг работы сайта невозможны без качественной системы логирования. 1С-Битрикс предоставляет гибкие инструменты для записи событий, ошибок и отладочной информации, основанные на стандарте PSR-3. В этой статье разберём все доступные логгеры, способы их настройки и интеграции в свои проекты.

Что такое PSR-3 и почему это важно

PSR-3 — это общепринятый стандарт PHP для интерфейсов логирования. Он определяет единые методы записи сообщений с разными уровнями важности: от emergency (критическая ошибка) до debug (отладочная информация). Все логгеры в Битрикс реализуют этот интерфейс, что делает их совместимыми с любыми PSR-3-совместимыми библиотеками (например, Monolog).

Уровни логирования задаются константами LogLevel::*. Вы можете выбрать, начиная с какого уровня сообщения будут попадать в лог, игнорируя менее важные.

Какие логгеры есть в Битрикс

Ядро предлагает четыре готовых логгера, каждый со своим назначением:

FileLogger — запись в файл

Самый часто используемый логгер. Пишет сообщения в указанный файл. Поддерживает автоматическую ротацию: при превышении заданного размера (по умолчанию 1 МБ) старый файл сохраняется с суффиксом .old, а новый начинает запись с нуля. Ротацию можно отключить, установив $maxLogSize = 0.

Когда использовать: для отладки, записи ошибок модуля, мониторинга работы скриптов.

SysLogger — запись в системный журнал

Отправляет сообщения в syslog сервера через функцию syslog(). Позволяет указать идентификатор (например, название модуля) и facility (категорию сообщений).

Когда использовать: если вы хотите централизованно собирать логи сервера или использовать стандартные утилиты мониторинга.

EventLogger — запись в таблицу b_event_log

Сохраняет события в базу данных, в таблицу системных логов. Можно передать callback, который будет изменять поля записи на основе контекста.

Когда использовать: если нужно хранить логи в БД для последующего анализа в админке или интеграции с другими модулями.

Как настроить форматирование сообщений

Логгеры используют форматтер — объект, который преобразует сообщение и контекст в строку для записи. По умолчанию применяется LogFormatter, который умеет подставлять значения из контекста в плейсхолдеры вида {ключ}.

Доступны автоматические плейсхолдеры:

• {date} — текущая дата и время;
• {host} — HTTP-хост;
• {exception} — объект исключения;
• {trace} — стек вызовов;
• {delimiter} — разделитель сообщений.

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

С версии 25.300.0 доступен форматтер JsonLinesFormatter, который выводит контекст в формате JSON Lines — по одной записи на строку. Это удобно для машинной обработки логов.

Способы подключения логгера к классу

Есть три основных подхода: ручная передача, использование фабрики и внедрение зависимостей через DI-контейнер.

Ручная передача (LoggerAwareInterface)

Самый простой способ — реализовать интерфейс LoggerAwareInterface и использовать трейт LoggerAwareTrait. Тогда в любой момент вы можете передать логгер через метод setLogger().

Получение логгера через фабрику

Если вы не можете или не хотите вручную передавать логгер, воспользуйтесь встроенной фабрикой Logger::create($id, $parameters). Она создаёт логгер по идентификатору, указанному в конфигурации .settings.php. Это удобно для внедрения логгера внутрь класса без изменения внешнего кода.

Внедрение через DI-контейнер

Для современных модулей рекомендуется использовать сервис-контейнер. В файле .settings.php модуля можно описать, как создаётся экземпляр класса с нужным логгером. Это даёт максимальную гибкость и позволяет подключать любые PSR-3-совместимые логгеры, включая сторонние (например, Monolog).

Настройка логгеров в .settings.php

Глобальная конфигурация логгеров выполняется в файле /bitrix/.settings.php в секции loggers. Каждый логгер определяется идентификатором и может содержать:

• constructor — замыкание, которое возвращает экземпляр логгера;
• level — минимальный уровень логирования;
• formatter — идентификатор форматтера из секции services.

Если используется замыкание, его следует размещать в файле .settings_extra.php, чтобы оно не сбрасывалось при обновлении настроек через админку.

Пример: логирование HTTP-клиента

Класс HttpClient активно использует логгер с идентификатором main.HttpClient. Фабрика передаёт в конструктор объекты DebugInterface и RequestInterface, что позволяет динамически настраивать уровень отладки и имя файла для каждого запроса.

NullLogger — когда не нужно ничего писать

Иногда удобно иметь объект логгера, который ничего не делает, чтобы не проверять его наличие перед каждым вызовом. NullLogger реализует все методы PSR-3, но игнорирует сообщения. Это полезно, если вы хотите оставить вызовы $logger->info() в коде, но в определённых условиях отключать запись.

Итоги и рекомендации

Правильно настроенное логирование — залог быстрого поиска ошибок и понимания того, что происходит на сайте. Используйте разные логгеры для разных задач:

• FileLogger — для ежедневной отладки и мониторинга.
• SysLogger — если у вас централизованный сбор логов.
• EventLogger — для событий, которые нужно показывать в админке.

Не забывайте про форматирование: добавляйте в контекст полезную информацию (ID пользователя, URL запроса), чтобы логи были информативными. И всегда используйте PSR-3 интерфейс — это сделает ваш код универсальным и готовым к любым изменениям.