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

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

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

Как настроить журналы Laravel

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

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

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

// Using the Log facade
use Illuminate\Support\Facades\Log;

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

// Using the log helper function
log('Order placed', ['order_id' => $order->id]);

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

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

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

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

  • Используйте debug для получения подробной информации, полезной для целей отладки, такой как значения переменных, вызовы функций или запросы SQL.
  • Используйте info для общей информации, полезной для понимания нормального потока вашего приложения, такой как действия пользователя, системные события или показатели производительности.
  • Используйте notice для важной информации, которая не является ошибкой, но может потребовать внимания, например, изменения конфигурации, устаревание функций или проблемы с внешними службами.
  • Используйте warning для потенциальных проблем, которые могут повлиять на функциональность или производительность вашего приложения, но не являются критическими или фатальными, такими как ошибки проверки, недостающие ресурсы или медленные ответы.
  • Используйте error для фактических ошибок, которые мешают вашему приложению выполнять намеченную задачу, таких как исключения, ошибки базы данных или сбои сети.
  • Используйте critical для серьезных ошибок, которые требуют немедленного внимания и могут привести к сбою или недоступности приложения, например утечка памяти, сбой диска или нарушение безопасности.
  • Используйте alert для экстренных ошибок, которые требуют вмешательства человека и могут повлиять на другие системы или службы, зависящие от вашего приложения, например сбои платежей, повреждение данных или перегрузка системы.
  • Используйте emergency для катастрофических ошибок, которые делают ваше приложение полностью непригодным для использования и могут потребовать перезагрузки или восстановления системы, таких как паники ядра, аппаратные сбои или перебои в подаче электроэнергии.

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

Log::error('Database connection failed', [
    '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');

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

// 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. Вы можете изменить различные настройки, такие как путь к хранилищу журнала, маршрут просмотра журнала, тему пользовательского интерфейса просмотра журнала и т. д.

Для получения дополнительной информации о Log Viewer вы можете посетить его репозиторий GitHub: https://github.com/opcodesio/log-viewer.

Заключение

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

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