Monolog в PHP: логирование, сравнение с error_log и 12 примеров

Пользователь увидел ошибку, задача в очереди остановилась, внешний API ответил неожиданно — разработчику нужно восстановить ход событий. Для этого приложение записывает журнал: что произошло, когда, насколько это серьёзно и какие безопасные данные помогут разобраться. Monolog позволяет организовать такую запись единообразно для всего PHP-проекта.

Статья посвящена Monolog 3. Учебный проект рассчитан на PHP 8.2+, запускается в терминале и пишет только в свою папку var/log/. Внешние сервисы не нужны. Если Composer ещё не установлен, начните с руководства по Composer: установка, зависимости и автозагрузка.

1. Установка и первая запись

В существующем проекте установите библиотеку:

composer require "monolog/monolog:3.*"
composer show monolog/monolog

Для практики по статье скачайте готовый ZIP, распакуйте его и перейдите в папку с composer.json. В архиве есть lock-файл с проверенными версиями; папки vendor/ нет, поэтому при первой установке потребуется интернет:

composer install
composer check-platform-reqs
composer first

Полный файл first.php:

<?php
declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use Monolog\Handler\StreamHandler;
use Monolog\Level;
use Monolog\Logger;
use Monolog\Processor\PsrLogMessageProcessor;

$logDir = __DIR__ . '/var/log';
if (!is_dir($logDir) && !mkdir($logDir, 0770, true) && !is_dir($logDir)) {
    throw new RuntimeException('Не удалось создать папку журнала.');
}
$logger = new Logger('app');
$logger->pushHandler(new StreamHandler($logDir . '/app.log', Level::Info));
$logger->pushProcessor(new PsrLogMessageProcessor());

$logger->debug('Отладочная запись: ниже порога Info.');
$logger->info('Заказ {order_id} создан', ['order_id' => 1042]);
$logger->warning('Ответ API задерживается', ['duration_ms' => 1800]);
$logger->close();

echo "В var/log/app.log добавлены INFO и WARNING; DEBUG отфильтрован." . PHP_EOL;

Команда composer first запускает этот файл; можно выполнить и php first.php. Смотрите созданный файл var/log/app.log. В нём появятся INFO и WARNING с временем, каналом, сообщением и контекстом; DEBUG отфильтруется. При повторном запуске записи добавляются в конец.

После метки времени строка INFO будет выглядеть так: app.INFO: Заказ 1042 создан {"order_id":1042} []. Время зависит от момента запуска и настроек PHP, app — имя канала, order_id — полезное поле контекста. Последние [] означают, что дополнительных полей extra пока нет.

Просмотр последних строк:

PowerShell:

Get-Content ./var/log/app.log -Tail 10

Linux/macOS:

tail -n 10 var/log/app.log

<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';

$logDir = __DIR__ . '/var/log';
if (!is_dir($logDir) && !mkdir($logDir, 0775, true) && !is_dir($logDir)) {
    throw new RuntimeException('Не удалось создать каталог логов.');
}

// Ниже добавьте один фрагмент из статьи.

Подробнее: Monolog: установка и требования.

2. Monolog и стандартный error_log

error_log() доступна в самом PHP и подходит для простой диагностической записи. Monolog — библиотека, которая добавляет единый интерфейс уровней, контекст, настройку форматов, обработчики и правила маршрутизации. Он также умеет писать через error_log() с помощью ErrorLogHandler: эти инструменты могут использоваться вместе.

Одно событие двумя способами. Файлы ниже будут содержать сведения об одном учебном заказе. Для сравнения используйте следующую подготовку вместо предыдущего начала experiment.php: она уже содержит <?php и автозагрузку. После неё добавьте один или оба варианта записи. Не вставляйте второй открывающий тег PHP в середину файла.

<?php
declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$logDir = __DIR__ . '/var/log';
if (!is_dir($logDir) && !mkdir($logDir, 0770, true) && !is_dir($logDir)) {
    throw new RuntimeException('Не удалось создать папку журнала.');
}
$orderId = 1042;
$context = ['order_id' => $orderId, 'request_id' => 'demo-001'];

Нативный PHP:

$record = [
    'datetime' => (new DateTimeImmutable())->format(DATE_ATOM),
    'channel' => 'orders',
    'level_name' => 'INFO',
    'message' => 'Заказ ' . $orderId . ' создан',
    'context' => $context,
];
$line = json_encode($record, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR) . PHP_EOL;
if (!error_log($line, 3, $logDir . '/native.jsonl')) {
    throw new RuntimeException('Не удалось записать журнал.');
}

Monolog:

$handler = new Monolog\Handler\StreamHandler($logDir . '/monolog.jsonl', Monolog\Level::Info);
$handler->setFormatter(new Monolog\Formatter\JsonFormatter());

$logger = new Monolog\Logger('orders');
$logger->pushHandler($handler);
$logger->pushProcessor(new Monolog\Processor\PsrLogMessageProcessor());

$logger->info('Заказ {order_id} создан', $context);
$logger->close();

Полный вариант находится в error-log-vs-monolog.php. Запустите composer compare: он запишет событие обоими способами и проверит поля. Monolog берёт на себя оформление времени, канала и уровня; в варианте error_log() эти данные формирует ваш код. JSON можно получить в обоих случаях.

Когда что выбрать? Для короткого разового скрипта error_log() может быть достаточно. Если нужны единые события в нескольких модулях, разные уровни, JSON, ротация и тестирование, Monolog помогает сосредоточить правила в одной настройке. Ради одного сообщения добавлять библиотеку необязательно.

Подробнее: PHP: error_log, типы записи и результат.

3. Восемь уровней и порог записи

Уровень отвечает на вопрос «насколько событие серьёзно?». Договоритесь о значениях внутри команды: важно, чтобы похожие события получали одинаковую оценку. Ниже — практические ориентиры, а не обязательная классификация любого приложения.

Числа в таблице — шкала Monolog. Это не PHP-константы E_WARNING/E_ERROR. В коде удобнее использовать Monolog\Level, а для записи — методы debug(), info(), warning(), error() и остальные.

$logger = new Monolog\Logger('levels');
$logger->pushHandler(new Monolog\Handler\StreamHandler(
    $logDir . '/levels.log',
    Monolog\Level::Warning
));

$logger->debug('Промежуточный расчёт');
$logger->info('Операция завершена');
$logger->warning('Ответ сервиса занял больше обычного');
$logger->error('Не удалось завершить операцию');
$logger->close();

Результат: добавятся только WARNING и ERROR. Порог Warning пропускает этот уровень и все более серьёзные; он не означает «записывать только warning». Порог Debug пропустит все восемь уровней.

Подробнее: PSR-3: общий интерфейс логирования.

4. Logger, handler, formatter и processor

Чтобы настройка не выглядела набором непонятных классов, разделим обязанности:

В типичной настройке путь такой: вызов logger → подготовка записи и processors → подходящий handler → его formatter → место назначения. Processors также можно назначать конкретному handler. Несколько обработчиков могут получить одно событие, каждый со своим порогом и форматом.

Канал — имя вроде orders, payments или worker. Он помогает определить источник сообщения. Одно имя канала не создаёт автоматически отдельный файл: куда писать, решает handler.

5. Контекст и подстановка значений

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

$logger = new Monolog\Logger('orders');
$logger->pushHandler(new Monolog\Handler\StreamHandler(
    $logDir . '/context.log', Monolog\Level::Info
));
$logger->pushProcessor(new Monolog\Processor\PsrLogMessageProcessor());

$logger->info('Заказ {order_id} создан', [
    'order_id' => 1042,
    'items_count' => 3,
    'delivery' => 'pickup',
]);
$logger->close();

Сообщение станет Заказ 1042 создан; дополнительные данные останутся в контексте при обычных настройках этого processor. Без PsrLogMessageProcessor не стоит ожидать автоматической замены {order_id} в таком логгере. Подстановка в сообщение и сохранение структурированных полей — разные операции.

Общее поле для всех событий. Собственный processor в Monolog 3 получает LogRecord и возвращает запись:

$logger = new Monolog\Logger('worker');
$logger->pushHandler(new Monolog\Handler\StreamHandler(
    $logDir . '/processor.log', Monolog\Level::Info
));
$logger->pushProcessor(function (Monolog\LogRecord $record): Monolog\LogRecord {
    $record->extra['application'] = 'demo-worker';
    $record->extra['request_id'] = 'demo-request-001';
    return $record;
});
$logger->info('Начата обработка задания', ['job_id' => 42]);
$logger->close();

context описывает конкретное событие, extra удобно использовать для полей, добавленных processor. В реальном приложении request_id создаётся или проверяется на входе запроса; учебная строка здесь фиксирована для воспроизводимости.

Подробнее: Реализация подстановки PsrLogMessageProcessor.

6. Обычный текст и JSON

Строковый журнал удобно читать в терминале, JSON — разбирать программой и отправлять в систему поиска. Формат назначается обработчику.

$handler = new Monolog\Handler\StreamHandler(
    $logDir . '/events.jsonl', Monolog\Level::Info
);
$handler->setFormatter(new Monolog\Formatter\JsonFormatter());
$logger = new Monolog\Logger('orders', [$handler]);

$logger->info('Заказ создан', ['order_id' => 1042, 'amount' => 1500]);
$logger->close();

Каждое событие записывается отдельной JSON-строкой. В записи есть message, context, level, level_name, channel, datetime и extra. Это формат JSON Lines: весь файл из нескольких строк не является одним JSON-массивом. Читайте и декодируйте его построчно.

$handler->setFormatter(new Monolog\Formatter\LineFormatter(
    "[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n",
    'Y-m-d H:i:s'
));

7. Исключения и решение, что делать дальше

Передавайте объект исключения в ключе exception. Тогда formatter сможет извлечь класс, сообщение и другие диагностические сведения. Пример ниже — для локального CLI, ошибка создаётся намеренно:

$handler = new Monolog\Handler\StreamHandler(
    $logDir . '/exceptions.jsonl', Monolog\Level::Error
);
$formatter = new Monolog\Formatter\JsonFormatter();
$formatter->includeStacktraces(true);
$handler->setFormatter($formatter);
$logger = new Monolog\Logger('worker', [$handler]);

$processOrder = static function (): void {
    throw new RuntimeException('Учебный сбой обработки заказа');
};

try {
    $processOrder();
} catch (Throwable $e) {
    $logger->error('Обработка заказа не выполнена', [
        'order_id' => 1042,
        'exception' => $e,
    ]);
    $logger->close();
    fwrite(STDERR, "Не удалось обработать заказ. Подробности записаны в журнал.\n");
    exit(1);
}

Здесь три отдельных действия: catch перехватывает сбой, Monolog записывает сведения, а exit(1) сообщает оболочке о неуспешном выполнении. Если убрать exit, программа сможет продолжить работу после блока — иногда это нужно, иногда приведёт к неверному результату.

Учебная функция вызвана отдельно, чтобы в trace было видно место её вызова. Если бросить исключение прямо на верхнем уровне файла, стек вызовов может оказаться пустым даже при включённом includeStacktraces.

Для веб-приложения вместо CLI-вывода сформируйте корректный HTTP-ответ и понятное пользователю сообщение. Детальный trace оставьте в защищённом журнале. Не записывайте одно и то же исключение в каждом слое перед повторным throw: выберите ответственную границу, чтобы не получить несколько одинаковых событий.

Подробнее: PHP: исключения и распространение ошибки.

8. Предупреждения PHP и непойманные исключения

Вызовы $logger->warning() и $logger->error() записывают ваши события. Чтобы подключить Monolog к обработке диагностических событий самого PHP, существует ErrorHandler. В отдельном учебном скрипте можно зарегистрировать его так:

$logger = new Monolog\Logger('php');
$logger->pushHandler(new Monolog\Handler\StreamHandler(
    $logDir . '/php-errors.log', Monolog\Level::Debug
));
Monolog\ErrorHandler::register($logger);

trigger_error('Учебное предупреждение', E_USER_WARNING);
echo "Код после предупреждения выполнен.\n";

Обычное предупреждение не останавливает исполнение: следующая строка выполнится. В зависимости от настроек и предыдущего обработчика предупреждение также может попасть в штатный вывод/журнал PHP. ErrorHandler не превращает автоматически каждое предупреждение в выброшенное исключение.

Непойманное исключение — другой сценарий. В копии того же примера замените последние две строки следующими:

throw new RuntimeException('Учебное непойманное исключение');
echo "Эта строка не выполнится.\n";

Глобальный обработчик запишет исключение, но выполнение не вернётся к строке после throw. В архиве сценарии php-warning и uncaught выполняются отдельными процессами: проверяются и журнал, и факт продолжения/завершения.

Подробнее: Monolog ErrorHandler.

Подробнее: PHP: возможности и ограничения error handler.

9. Файлы, консоль и ротация

StreamHandler записывает в файл или PHP-поток. В контейнере и CLI может быть удобнее отправлять журнал в стандартный поток ошибок, а хранение и сбор поручить окружению:

$logger = new Monolog\Logger('cli');
$logger->pushHandler(new Monolog\Handler\StreamHandler(
    'php://stderr', Monolog\Level::Info
));
$logger->info('Начата обработка задания', ['job_id' => 42]);

Сообщение появится в stderr; оно не смешивается со stdout, куда скрипт может выводить данные. Кто хранит этот поток и как долго — отдельная настройка процесса, контейнера или платформы.

Файлы по датам. Для небольшого приложения можно использовать RotatingFileHandler:

$handler = new Monolog\Handler\RotatingFileHandler(
    $logDir . '/daily.log',
    7,
    Monolog\Level::Info
);
$logger = new Monolog\Logger('app', [$handler]);
$logger->info('Ежедневная проверка завершена');
$logger->close();

При обычных настройках имя будет вида daily-YYYY-MM-DD.log. Число 7 задаёт предел количества сохраняемых файлов этой ротации, а не размер файла в мегабайтах и не отдельный таймер удаления ровно через семь суток. Очистка выполняется при работе обработчика; файл за день всё равно может вырасти большим.

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

Подробнее: RotatingFileHandler: ротация и maxFiles.

10. Несколько обработчиков и каналы

Запишем INFO и выше в общий журнал, а ERROR и выше — ещё и в отдельный файл:

$all = new Monolog\Handler\StreamHandler(
    $logDir . '/all.log', Monolog\Level::Info
);
$errors = new Monolog\Handler\StreamHandler(
    $logDir . '/errors.log', Monolog\Level::Error
);
$logger = new Monolog\Logger('orders');
$logger->pushHandler($all);
$logger->pushHandler($errors);

$logger->info('Заказ создан', ['order_id' => 1042]);
$logger->error('Заказ не обработан', ['order_id' => 1043]);
$logger->close();

Ожидается: в all.log две записи, в errors.log одна — если смотреть только этот запуск. Последний добавленный через pushHandler() обработчик вызывается первым. По умолчанию обработанная запись может идти дальше по стеку.

Два канала в одном файле:

$handler = new Monolog\Handler\StreamHandler(
    $logDir . '/channels.log', Monolog\Level::Info
);
$orders = new Monolog\Logger('orders', [$handler]);
$worker = new Monolog\Logger('worker', [$handler]);

$orders->info('Заказ поставлен в очередь', ['order_id' => 1042]);
$worker->info('Задание получено', ['job_id' => 42]);
$handler->close();

Обе записи находятся в channels.log, но у них разные поля channel. Не создавайте новый Logger на каждую строку: настройте нужные каналы при запуске приложения и передавайте их компонентам.

Подробнее: Порядок обработчиков и каналы.

11. Предыстория ошибки: FingersCrossedHandler

Иногда полный DEBUG-журнал слишком шумный, но при сбое нужны предшествующие шаги. FingersCrossedHandler может сначала собирать записи в памяти, а при достижении выбранной серьёзности передать накопленное вложенному обработчику.

$file = new Monolog\Handler\StreamHandler(
    $logDir . '/incident.log', Monolog\Level::Debug
);
$buffer = new Monolog\Handler\FingersCrossedHandler(
    $file,
    Monolog\Level::Error,
    50
);
$logger = new Monolog\Logger('checkout', [$buffer]);

$logger->debug('Начинаем проверку заказа');
$logger->info('Товары найдены', ['items_count' => 3]);
$logger->error('Не удалось завершить заказ');
$logger->close();

В incident.log попадут все три записи: ERROR активирует буфер и раскрывает предысторию. Если убрать ERROR, эти DEBUG/INFO в данной конфигурации не будут записаны. Внутренний handler настроен на Debug специально: если поставить ему Error, он отфильтрует полезную предысторию.

Параметр 50 ограничивает буфер количеством записей, не байтами. Не кладите в context огромные объекты. Для долгоживущего обработчика очереди завершайте цикл после задания: $logger->reset() сбрасывает состояние поддерживающих это handlers/processors. Это не удаляет уже записанные файлы и не заменяет установку нового request_id для следующей задачи.

Подробнее: FingersCrossedHandler: активация и буфер.

12. Как подключать логирование к своему коду

Классу приложения полезнее зависеть от Psr\Log\LoggerInterface, чем самому создавать путь к файлу. Тогда формат и место записи задаются снаружи, а в тесте можно использовать другой logger.

final class OrderService
{
    public function __construct(private Psr\Log\LoggerInterface $logger)
    {
    }

    public function prepare(int $orderId): void
    {
        if ($orderId <= 0) {
            throw new InvalidArgumentException('Некорректный номер заказа.');
        }
        $this->logger->info('Заказ подготовлен', ['order_id' => $orderId]);
    }
}

$logger = new Monolog\Logger('orders', [
    new Monolog\Handler\StreamHandler($logDir . '/service.log', Monolog\Level::Info),
]);
$service = new OrderService($logger);
$service->prepare(1042);
$logger->close();

Пример показывает передачу зависимости; метод не создаёт заказ в базе. Ошибку некорректного аргумента должен обработать вызывающий код на выбранной границе. Для теста самого класса можно передать Psr\Log\NullLogger, если журнал не проверяется, либо Monolog с TestHandler, если нужно проверить событие.

Где ставить записи в интеграции: перед важным этапом — безопасный идентификатор операции; при успехе — результат и длительность; при отказе — понятное событие и диагностические поля. Если используете HTTP-клиент, рядом пригодится статья о Guzzle, запросах и исключениях. Секретные заголовки и полное тело ответа не должны автоматически становиться контекстом лога.

Подробнее: Обработчики, форматы и processors.

13. Готовый проект: 12 сценариев

Скачать примеры Monolog — ZIP

Архив содержит исходники, README, lock-файл и сведения о проверке. Внешних уведомлений и подключения к серверу не требуется. После composer install запустите:

composer first
composer compare
composer demo -- list
composer demo -- all

Где смотреть результат? first дописывает в var/log/app.log. Каждый запуск compare создаёт новую папку var/log/compare-…, а запуск самопроверки — var/log/run-…; сценарии одного запуска пишут разные файлы в этой общей папке. Конкретный путь выводится в терминале. README объясняет ожидаемые записи и файлы. Проект не меняет системный php.ini.

Проверено 6 ноября 2026 года: PHP 8.3.33, Composer 2.10.3, Monolog 3.12.1 и psr/log 3.0.2, Windows. Прошли 12 из 12 сценариев, первый пример и сравнение с error_log. Журналы действительно записывались в файлы; JSON и ожидаемые поля проверялись программно. Предупреждение PHP и непойманное исключение проверены в отдельных процессах: после warning выполнение продолжилось, после uncaught процесс завершился с кодом 255. Исходные PHP-файлы прошли проверку синтаксиса, а зависимости — composer validate --strict, composer check-platform-reqs и composer audit --locked. Известных advisories для зафиксированных зависимостей на момент проверки не обнаружено.

Дополнительно все 19 PHP-блоков статьи прошли синтаксическую проверку и локальный запуск с указанной подготовкой. Проверены содержимое файлов, пороги, context/extra, JSON, настоящий перевод строки LineFormatter, непустой trace, маршрутизация по handlers, каналы и буферизация. Для примера с явным exit(1) ожидается код 1, для непойманного исключения — 255; это подтверждённое поведение примеров, а не провал проверки.

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

14. Диагностика и частые ошибки

Команды, с которых удобно начать проверку окружения:

php --version
php --ini
composer show monolog/monolog
composer check-platform-reqs
composer diagnose
composer audit

15. Источники и дальнейшая практика

• Monolog: официальный репозиторий — документация, исходники и версии.
• Руководство по использованию — каналы, уровни, обработчики и жизненный цикл.
• PSR-3 — интерфейс логирования, context и exception.
• PHP: error_log() и глобальный обработчик исключений.
• Composer в PHP — установка, зависимости, lock-файл и команды.
• Guzzle в PHP — HTTP-запросы и обработка отказов внешнего API.
• Скачать проект с примерами Monolog.

Для закрепления поменяйте порог с Info на Warning, добавьте своё безопасное поле context и сравните текстовый журнал с JSON. Затем выберите одну операцию своего приложения и опишите три события: начало, успешное завершение и отказ. Для каждого заранее определите полезные поля и дальнейшее действие программы.