Опубликовано:

Искусство записи Laravel Логов: Рекомендации и примеры

Источник: «The Art of Writing Laravel Logs: Best Practices and Examples»
Laravel — популярный PHP-фреймворк обеспечивающий простой и элегантный способ создания веб-приложений. Одной из особенностей выделяющих Laravel, является его мощная и гибкая система ведения логов/логирование.

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

В этой статье мы рассмотрим некоторые из рекомендаций и примеров записи Laravel логов. Мы рассмотрим следующие темы:

Как настроить Laravel логи

Конфигурация ведения лога Laravel храниться в файле config/logging.php. Этот файл определяет несколько каналов логирования, представляющих собой группы обработчиков логов с общим именем и конфигурацией. Например, канал по умолчанию использует один файл лога в каталоге storage/logs, а канал daily использует меняющийся набор файлов, которые создаются каждый день.

Вы можете указать, какой канал использовать, задав переменную среды LOG_CHANNEL в файле .env. Вы также можете создавать свои собственные настраиваемые каналы, добавляя их в файл config/logging.php. Например, вы можете создать канал, который ведёт лог в таблице базы данных или отправляет уведомления по электронной почте.

Для получения доступа к функциям логирования в коде, можно использовать фасад Log или хелпер log. Оба этих метода предоставляют простой интерфейс для записи сообщений лога с различным уровнем серьёзности: debug, info, notice, warning, error, critical, alert и emergency. Например:

// Использование фасада Log
use Illuminate\Support\Facades\Log;

Log::info('User registered', ['name' => $user->name]);

// Использование хелпера log
log('Order placed', ['order_id' => $order->id]);

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

Log::channel('slack')->error('Something went wrong');

Как записать в лог сообщения с разными уровнями серьёзности

При записи сообщений лога важно выбрать соответствующий уровень серьёзности для каждого сообщения. Это поможет отфильтровать логи и расставить их по приоритетам в зависимости от важности и срочности. Вот несколько общих рекомендаций по выбору уровня записи в лог:

При записи сообщений в лог также рекомендуется включать релевантную контекстную информацию, которая может помочь определить источник и причину проблемы. Например, вы можете включить идентификаторы пользователей, идентификаторы запросов, идентификаторы сеансов, IP-адреса, URL-адреса, параметры, трассировку стека и т.д. Вы можете передавать эту информацию в виде массива в качестве второго аргумента методов ведения логов:

Log::error('Ошибка подключения к базе данных', [
    'host' => $host,
    'port' => $port,
    'user' => $user,
    'password' => $password,
    'exception' => $e,
]);

Как использовать настраиваемые каналы и обработчики Monolog

Система логирования Laravel построена поверх Monolog, это означает, что вы можете использовать её богатый набор возможностей и интеграций. Monolog поддерживает различные обработчики логов, которые могут записывать сообщения лога в разные места назначения и форматы. Например, вы можете писать лог в базу данных, канал Slack, на адрес электронной почты, веб сервис и т.д. Вы также можете настроить форматирование и обработку сообщений лога перед отправкой обработчикам.

Чтобы использовать собственный канал или обработчик Monolog, необходимо зарегистрировать его в файле config/logging.php. Например, если вы хотите использовать обработчик Slack для отправки сообщений лога в канал Slack, необходимо установить пакет monolog/slack и добавить новый канал следующим образом:

// config/logging.php

return [

    // ...

    'channels' => [
        // ...

        'slack' => [
            'driver' => 'monolog',
            'handler' => Monolog\Handler\SlackWebhookHandler::class,
            'handler_with' => [
                'webhookUrl' => env('SLACK_WEBHOOK_URL'),
                'channel' => env('SLACK_CHANNEL'),
                'username' => env('SLACK_USERNAME'),
                'emoji' => env('SLACK_EMOJI'),
            ],
        ],

    ],

];

Затем вы можете использовать этот канал в своём коде:

Log::channel('slack')->info('Hello from Laravel');

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

// config/logging.php

return [

    // ...

    'channels' => [
        // ...

        'error' => [
            'driver' => 'stack',
            'channels' => ['error_file', 'error_email'],
        ],

        'error_file' => [
            'driver' => 'monolog',
            'handler' => Monolog\Handler\StreamHandler::class,
            'handler_with' => [
                'stream' => storage_path('logs/error.log'),
                'level' => Monolog\Logger::ERROR,
            ],
        ],

        'error_email' => [
            'driver' => 'monolog',
            'handler' => Monolog\Handler\NativeMailerHandler::class,
            'handler_with' => [
                'to' => env('ERROR_EMAIL_TO'),
                'subject' => env('ERROR_EMAIL_SUBJECT'),
                'from' => env('ERROR_EMAIL_FROM'),
                'level' => Monolog\Logger::CRITICAL,
            ],
        ],

    ],

];

Затем вы можете использовать этот канал в приложении:

Log::channel('error')->error('Something went wrong');

Как использовать обработчик исключений Laravel для логирования ошибок

Обработчик исключений Laravel — это класс обрабатывающий все исключения создаваемые приложением. Он находится в файле app/Exceptions/Handler.php. Этот класс имеет два метода: report и render.

Метод report отвечает за логирование исключения или его отправку во внешний сервис, например Sentry или Bugsnag. По умолчанию он использует фасад Log для логирования исключения в канале по умолчанию. Вы можете настроить это поведение, переопределив этот метод в своём классе обработчика. Например, вы можете регистрировать различные типы исключений в разных каналах:

// app/Exceptions/Handler.php

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Throwable;

class Handler extends ExceptionHandler
{
    // ...

    public function report(Throwable $exception)
    {
        if ($exception instanceof \Illuminate\Database\QueryException) {
            Log::channel('database')->error($exception);
        } elseif ($exception instanceof \Illuminate\Auth\AuthenticationException) {
            Log::channel('auth')->warning($exception);
        } else {
            parent::report($exception);
        }
    }

    // ...
}

Метод render отвечает за преобразование исключения в HTTP ответ отправляемый обратно пользователю. По умолчанию он использует встроенные представления ошибок Laravel или JSON в зависимости от типа запроса. Вы можете настроить это поведение, переопределив этот метод в своём классе обработчика. Например, вы можете вернуть собственное представление для конкретного исключения:

// app/Exceptions/Handler.php

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Throwable;

class Handler extends ExceptionHandler
{
    // ...

    public function render($request, Throwable $exception)
    {
        if ($exception instanceof \App\Exceptions\CustomException) {
            return response()->view('errors.custom', [], 500);
        }

        return parent::render($request, $exception);
    }

    // ...
}

Как использовать веб-интерфейс для Laravel логов с помощью Log Viewer

Log Viewer — сторонний пакет, предоставляющий быстрый и красивый веб-интерфейс для просмотра Laravel логов. Он позволяет просматривать все логи Laravel в каталоге storage/logs, искать логи, фильтровать по уровню лога, делится ссылками на отдельные записи логов, загружать и удалять файлы логов и многое другое. Он также поддерживает несколько хостов и логи Horizon.

Устанавливается Log Viewer следующей командой:

composer require opcodesio/log-viewer

После установки пакета вы можете получить доступ к Log Viewer в браузере по адресу {APP_URL}/log-viewer. Например: https://my-app.test/log-viewer.

Также вы можете настроить конфигурацию Log Viewer, опубликовав его файл конфигурации:

php artisan vendor:publish --provider="Opcodes\LogViewer\LogViewerServiceProvider"

Файл конфигурации будет размещён в config/log-viewer.php. Вы можете изменить его настройки, например путь к хранилищу логов, маршрут просмотра логов, тему UI просмотра логов и т.д.

Больше информации о Log Viewer можно узнать в его репозитории на GitHub

Заключение

В этой статье мы узнали, как использовать систему логирования Laravel для написания и управления сообщениями логов в приложении. Му увидели, как настраивать Laravel логи, ка писать сообщения в лог с разными уровнями серьёзности, как настраивать каналы и обработчики Monolog и как использовать обработчик исключений Laravel для логирования ошибок. Мы также рассмотрели несколько советов и примеров записи Laravel логов.

Ведение логов неотъемлемая часть разработки и обслуживания любого веб-приложения. Это помогает отслеживать производительность приложения, устранять проблемы и улучшать качество кода. Laravel логирование простое и понятное благодаря мощной и гибкой системе ведения логов. Мы надеемся, что эта статья помогла понять и оценить искусство ведения логов в Laravel. Удачного логирования!

Предыдущая Статья

CGI, FastCGI, php-fpm, nginx и Laravel

Следующая Статья

Новое в Symfony 6.3 — Интеграция Webhook с Mailer и Notifier