Laravel в production: уровни логирования и трассировка запросов через Correlation ID

Введение

Логирование — это не просто «записать что-то в файл». Это инструмент, который спасает часы отладки в production, помогает понять поведение системы и быстро находить причины ошибок. В этой статье разберём два ключевых аспекта: уровни логирования и correlation_id — технику, которая связывает все события одного запроса в единую цепочку.

Уровни логирования в Laravel

Laravel использует библиотеку Monolog и поддерживает стандартные уровни логирования PSR-3. Каждый уровень предназначен для определённого типа событий.

DEBUG — отладочная информация

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

Log::debug('Query executed', [
    'sql' => 'SELECT * FROM hosts',
    'time' => '12ms',
]);

INFO — штатные события

Бизнес-события, которые происходят в нормальном режиме работы: создание записей, успешные операции, авторизация пользователей.

Log::info('Host created', [
    'host_id' => $host->id,
    'hostname' => $host->hostname,
]);

WARNING — подозрительное поведение

Что-то нештатное, но система продолжает работать. Например, приближение к лимитам, устаревшие методы API, подозрительная активность.

Log::warning('Rate limit approaching', [
    'user_id' => $user->id,
    'requests' => 95,
    'limit' => 100,
]);

ERROR — операция не выполнена

Ошибка, которая помешала выполнить конкретную операцию, но не сломала всю систему.

Log::error('Failed to rename host', [
    'host_id' => $host->id,
    'error' => $exception->getMessage(),
]);

CRITICAL — система в опасности

Критическая ошибка, которая может привести к падению системы. Требует немедленного внимания.

Log::critical('Database connection lost', [
    'host' => config('database.connections.pgsql.host'),
    'error' => $exception->getMessage(),
]);

Как выглядит в логах

[2026-02-03 18:00:00] local.DEBUG: Query executed {"sql":"SELECT * FROM hosts","time":"12ms"}
[2026-02-03 18:00:01] local.INFO: Host created {"host_id":"abc-123","hostname":"web-01"}
[2026-02-03 18:00:02] local.WARNING: Rate limit approaching {"user_id":1,"requests":95,"limit":100}
[2026-02-03 18:00:03] local.ERROR: Failed to rename host {"host_id":"abc-123","error":"Connection refused"}
[2026-02-03 18:00:04] local.CRITICAL: Database connection lost {"host":"db","error":"Connection refused"}

Фильтрация по уровню

В .env можно настроить минимальный уровень логирования:

LOG_LEVEL=debug     # Всё (для разработки)
LOG_LEVEL=info      # info и выше (production)
LOG_LEVEL=warning   # Только warning, error, critical
LOG_LEVEL=error     # Только error и critical

Таблица: когда какой уровень использовать

Уровень	Когда использовать
debug	Детали для отладки, SQL, переменные
info	Успешные операции, бизнес-события
warning	Что-то подозрительное, но система работает
error	Операция не выполнена, нужно внимание
critical	Система может упасть, срочно чинить

Correlation ID: связываем события в цепочку

Представьте: один HTTP-запрос порождает цепочку событий — контроллер создаёт запись, ставит Job в очередь, Job выполняется воркером, отправляется email. Как потом найти все эти события в логах?

Проблема: хаос в логах

Без специальной «подписи» запроса логи выглядят так:

[18:00:01] INFO: Host rename requested {"host_id":"abc"}
[18:00:01] INFO: User logged in {"user_id":"xyz"}           // другой запрос
[18:00:01] INFO: Operation created {"operation_id":"123"}   // какой запрос?
[18:00:02] INFO: Email sent {"to":"user@mail.com"}          // какой запрос?
[18:00:02] ERROR: Connection refused                        // ???

Когда в системе сотни запросов в секунду, найти связанные события становится невозможно.

Решение: Correlation ID

Correlation ID — это уникальный идентификатор, который присваивается запросу и передаётся через всю цепочку обработки:

[18:00:01] [req-111] INFO: Host rename requested {"host_id":"abc"}
[18:00:01] [req-222] INFO: User logged in {"user_id":"xyz"}
[18:00:01] [req-111] INFO: Operation created {"operation_id":"123"}
[18:00:02] [req-222] INFO: Email sent {"to":"user@mail.com"}
[18:00:02] [req-111] ERROR: Connection refused

Теперь сразу видно: ошибка «Connection refused» относится к запросу req-111, который переименовывал хост.

Что можно делать с Correlation ID

1. Быстрый поиск по логам

# Найти всё, что связано с одним запросом
grep "527f12df-3991-4bca-b67e-3e655a868275" storage/logs/laravel.log

2. Отладка в production

Пользователь пишет: «У меня ошибка!». Вы просите correlation_id из заголовка ответа и мгновенно находите всю цепочку событий:

grep "527f12df" /var/log/app/*.log

3. Трассировка между микросервисами

Correlation ID можно передавать в заголовках при вызове внешних сервисов:

Http::withHeaders([
    'X-Correlation-ID' => $correlationId,
])->post('https://other-service/api/...');

Теперь один ID связывает события через API Gateway, Auth Service, Hosts Service и Queue Worker.

4. Мониторинг и алерты

В системах вроде Kibana, Grafana Loki или Datadog можно:

• Искать все события по correlation_id
• Строить графики времени выполнения запросов
• Настраивать алерты: «10% запросов с ошибками за последний час»

Реализация в Laravel

Создайте middleware, который генерирует или читает correlation_id:

class CorrelationId
{
    public function handle(Request $request, Closure $next): Response
    {
        // Получаем из заголовка или генерируем новый
        $correlationId = $request->header('X-Correlation-ID') ?? Str::uuid()->toString();

        // Добавляем в контекст логгера
        Log::shareContext(['correlation_id' => $correlationId]);

        $response = $next($request);

        // Возвращаем в заголовке ответа
        $response->headers->set('X-Correlation-ID', $correlationId);

        return $response;
    }
}

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

Итого: что даёт Correlation ID

Без Correlation ID	С Correlation ID
«Где-то ошибка»	«Ошибка в запросе 527f12df»
Ищешь по времени	Ищешь по ID
Job не связан с запросом	Полная цепочка событий
Микросервисы — хаос	Трассировка через всю систему

Заключение

Правильное логирование — это фундамент observability. Используйте уровни логов осмысленно: debug для отладки, info для бизнес-событий, error для ошибок. Добавьте correlation_id, чтобы связать все события одного запроса — это сэкономит часы при разборе инцидентов в production.

Correlation ID — это по сути «подпись» запроса, которая путешествует вместе с ним через логи, очереди, микросервисы и внешние API. Всё, что порождено одним запросом, помечено одной подписью.

Пример реализации в моем GitHub

Обложка от lookstudio на Freepick