Зачем PSR-3 и Monolog?

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

Monolog является одним из самых популярных и функциональных логеров в мире PHP. В нём реализовано огромное количество хендлеров: вы можете писать логи в файл, отправлять их на почту, пушить в систему логирования, выводить в консоль браузера… Список можно долго продолжать, но кроме того, вы можете без проблем написать свою логику логера — Monolog легко поддаётся кастомизации и весьма гибко настраивается. Если вы ещё не знакомы с ним, самое время это исправить. В репозитории библиотеки находится подробная документация с описанием архитектуры логера и его возможностей.

При настройке логеров не забывайте учитывать объёмы производимых ими записей. И помните, что ваша программа может в любой момент дать сбой, который повлечёт за собой колоссальный прирост размеров логов и интенсивность их записи. Настраивайте ротацию логов, не пишите их в основную БД приложения, используйте специализированные системы агрегации логов, такие как Kibana, Sentry, Gray2Log.

Логеры: конфигурация и применение

Настройки логеров нужно описывать в .settings.php. Это, практически, реализация шаблона «Сервис-локатор» (да, и этого в «Битриксе» тоже нет), за небольшим исключением. С таким подходом код приложения получает логер извне, как зависимость. Нет необходимости смешивать бизнес-логику с настройками. Кроме того, настройки логеров могут легко меняться без изменения кода приложения.

Материал по теме: «Проблема инициализации объектов в ООП приложениях на PHP. Поиск решения при помощи шаблонов Registry, Factory Method, Service Locator и Dependency Injection».

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

<?php

// .settings.php

return array(
    'monolog' => array(
        'value' => array(
            'handlers' => array(
                'default' => array(
                    'class' => '\Monolog\Handler\StreamHandler',
                    'level' => 'DEBUG',
                    'stream' => '/path/to/logs/app.log'
                ),
                'feedback_event_log' => array(
                    'class' => '\Bex\Monolog\Handler\BitrixHandler',
                    'level' => 'DEBUG',
                    'event' => 'TYPE_FOR_EVENT_LOG',
                    'module' => 'vendor.module'
                ),
            ),
            'loggers' => array(
                'app' => array(
                    'handlers'=> array('default'),
                ),
                'feedback' => array(
                    'handlers'=> array('feedback_event_log'),
                )
            )
        ),
        'readonly' => false
    )
);

Логер app будет писать в файл, логер feedback — в журнал событий.

Теперь использовать логеры проще простого. Запрашивайте нужный логер в своих скриптах через Registry и пишите сообщения:

<?php


// Дебаг
$logger->debug('Debug message');

// Cообщение об ошибке
$logger->error('Error message');

// Информационное сообщение. Добавим контекст.
$logger->info('Failed create new message on feedback form', [
   'Invalid data' => $addResult->getErrorMessages(), // Запишем в контекст ошибки формы.
   'Form data' => $formRequest // И данные, переданные в форму.
]);

Непойманные исключения

В новом ядре «Битрикса» появилась возможность устанавливать свой логер для непойманных исключений. Понятное дело, из-за отсутствия поддержки PSR-3 так просто Monolog не подключить. Но адаптер решает и эту проблему, теперь вам просто нужно в .settings.php указать класс перехватчика исключений и название логера, отвечающего за них:

<?php

// .settings.php

return array(
    'exception_handling' => array(
        'value' => array(
            'log' => array(
                'class_name' => '\Bex\Monolog\ExceptionHandlerLog',
                'settings' => array(
                    'logger' => 'app',
                ),
            ),
        ),
        'readonly' => false
    ),
    'monolog' => array(
        'value' => array(
            'handlers' => array(
                'default' => array(
                    'class' => '\Monolog\Handler\StreamHandler',
                    'level' => 'DEBUG',
                    'stream' => '/path/to/logs/app.log'
                )
            ),
            'loggers' => array(
                'app' => array(
                    'handlers'=> array('default'),
                ),
            )
        ),
        'readonly' => false
    )
);

Журнал событий

В Monolog-адаптере присутствует BitrixHandler, позволяющий производить запись логов в журнал событий «Битрикса»:

<?php

use Bex\Monolog\Handler\BitrixHandler;
use Monolog\Logger;

$logger->pushHandler(new BitrixHandler('event_type', 'module', Logger::INFO));

В результате, записи лога будут отображаться в панели управления «Битрикса»:

***

Monolog сделает процесс внедрения логеров приятным удовольствием. Больше не нужно вспоминать недокументированное API «Битрикса», выносить его в сниппеты. Внедрение дебаг-логов легко закладывается сразу же при разработке кода программы и ещё проще производится их отключение и включение. Смена места хранения логов не потребует внесения изменений в код приложения. А широкий спектр хендлеров, форматеров и процессоров позволит весьма гибко настраивать сбор логов.