Unetway

Laravel - Logging

Вступление

Чтобы помочь вам узнать больше о том, что происходит в вашем приложении, Laravel предоставляет надежные службы ведения журналов, которые позволяют записывать сообщения в файлы, журнал системных ошибок и даже в Slack, чтобы уведомить всю вашу команду.

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

 

Конфигурация

Вся конфигурация для системы регистрации вашего приложения находится в файле конфигурации. Этот файл позволяет настроить каналы журналов вашего приложения, поэтому обязательно просмотрите каждый из доступных каналов и их параметры. Мы рассмотрим несколько распространенных вариантов ниже.config/logging.php

По умолчанию Laravel будет использовать stackканал при регистрации сообщений. stackКанал используется для объединения нескольких каналов журнала в один канал. Для получения дополнительной информации о строительных стеках, ознакомьтесь с документацией ниже .

Настройка имени канала

По умолчанию Monolog создается с «именем канала», которое соответствует текущей среде, например, productionили local. Чтобы изменить это значение, добавьте nameпараметр в конфигурацию вашего канала:

'stack' => [
    'driver' => 'stack',
    'name' => 'channel-name',
    'channels' => ['single', 'slack'],
],

Доступные драйверы канала

название Описание
stack Обертка для облегчения создания "многоканальных" каналов
single Канал логгера на основе одного файла или пути ( StreamHandler)
daily RotatingFileHandlerДрайвер на основе Монолог , который вращается ежедневно
slack SlackWebhookHandlerДрайвер Монолог на основе
papertrail SyslogUdpHandlerДрайвер Монолог на основе
syslog SyslogHandlerДрайвер Монолог на основе
errorlog ErrorLogHandlerДрайвер Монолог на основе
monolog Заводской драйвер Monolog, который может использовать любой поддерживаемый обработчик Monolog
custom Драйвер, который вызывает указанную фабрику для создания канала

Проверьте документацию по расширенному каналу настройки , чтобы узнать больше о monologи customводителях.

Настройка одиночного и дневного каналов

singleИ dailyканалы имеют три дополнительных опций конфигурации: bubblepermissionи locking.

название Описание По умолчанию
bubble Указывает, должны ли сообщения пузыриться к другим каналам после обработки true
permission Разрешения файла журнала 0644
locking Попытайтесь заблокировать файл журнала перед записью в него false

Настройка канала Papertrail

Для papertrailканала требуются параметры конфигурации urlи port. Вы можете получить эти значения из Papertrail .

Настройка слабого канала

slackКанала требует urlпараметр конфигурации. Этот URL-адрес должен соответствовать URL-адресу входящего веб-крюка, который вы настроили для своей команды Slack.

 

Строительство бревен

Как упоминалось ранее, stackдрайвер позволяет объединять несколько каналов в один канал регистрации. Чтобы проиллюстрировать, как использовать стеки журналов, давайте рассмотрим пример конфигурации, которую вы можете увидеть в производственном приложении:

'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['syslog', 'slack'],
    ],

    'syslog' => [
        'driver' => 'syslog',
        'level' => 'debug',
    ],

    'slack' => [
        'driver' => 'slack',
        'url' => env('LOG_SLACK_WEBHOOK_URL'),
        'username' => 'Laravel Log',
        'emoji' => ':boom:',
        'level' => 'critical',
    ],
],

Давайте рассмотрим эту конфигурацию. Во-первых, обратите внимание, что наш stackканал объединяет два других канала с помощью своей channelsопции: syslogи slack. Таким образом, при регистрации сообщений оба канала будут иметь возможность регистрировать сообщения.

Уровни журнала

Обратите внимание на levelопцию конфигурации, присутствующую в конфигурациях каналов syslogи и slackв приведенном выше примере. Эта опция определяет минимальный «уровень» сообщения, который должен быть зарегистрирован для канала. Monolog, который поддерживает службы журналов Laravel, предлагает все уровни журналов, определенные в спецификации RFC 5424 : аварийный , аварийный , критический , ошибка , предупреждение , уведомление , информация и отладка .

Итак, представьте, что мы записываем сообщение, используя debugметод:

Log::debug('An informational message.');

Учитывая нашу конфигурацию, syslogканал запишет сообщение в системный журнал; однако, так как сообщение об ошибке не criticalуказано или выше, оно не будет отправлено в Slack. Однако, если мы зарегистрируем emergencyсообщение, оно будет отправлено как в системный журнал, так и в Slack, поскольку emergencyуровень выше нашего минимального порогового уровня для обоих каналов:

Log::emergency('The system is down!');

 

Написание сообщений журнала

Вы можете записать информацию в журналы, используя Log фасад . Как упоминалось ранее, регистратор предоставляет восемь уровней ведения журнала, определенных в спецификации RFC 5424 : аварийная ситуация , предупреждение , критическая ситуация , ошибка , предупреждение , уведомление , информация и отладка :

Log::emergency($message);
Log::alert($message);
Log::critical($message);
Log::error($message);
Log::warning($message);
Log::notice($message);
Log::info($message);
Log::debug($message);

Таким образом, вы можете вызвать любой из этих методов, чтобы записать сообщение для соответствующего уровня. По умолчанию сообщение будет записано в канал журнала по умолчанию, настроенный вашим файлом конфигурации:config/logging.php

<?php

namespace App\Http\Controllers;

use App\User;
use Illuminate\Support\Facades\Log;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
    /**
     * Show the profile for the given user.
     *
     * @param  int  $id
     * @return Response
     */
    public function showProfile($id)
    {
        Log::info('Showing user profile for user: '.$id);

        return view('user.profile', ['user' => User::findOrFail($id)]);
    }
}

Контекстная информация

Массив контекстных данных также может быть передан в методы журнала. Эти контекстные данные будут отформатированы и отображены в сообщении журнала:

Log::info('User failed to login.', ['id' => $user->id]);

 

Запись на определенные каналы

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

Log::channel('slack')->info('Something happened!');

Если вы хотите создать стек регистрации по требованию, состоящий из нескольких каналов, вы можете использовать stackметод:

Log::stack(['single', 'slack'])->info('Something happened!');

 

Расширенная настройка канала Monolog

Настройка Monolog для каналов

Иногда вам может понадобиться полный контроль над настройкой Monolog для существующего канала. Например, вы можете настроить пользовательскую FormatterInterfaceреализацию Monolog для обработчиков данного канала.

Для начала определите tapмассив в конфигурации канала. tapМассив должен содержать список классов , которые должны иметь возможность настроить (или «кран» в) экземпляр Монолог после ее создания:

'single' => [
    'driver' => 'single',
    'tap' => [App\Logging\CustomizeFormatter::class],
    'path' => storage_path('logs/laravel.log'),
    'level' => 'debug',
],

Как только вы настроили tapопцию на своем канале, вы готовы определить класс, который будет настраивать ваш экземпляр Monolog. Этому классу нужен только один метод:, __invokeкоторый получает экземпляр. В экземпляра прокси все вызовы методов базового Monolog например:Illuminate\Log\LoggerIlluminate\Log\Logger

<?php

namespace App\Logging;

class CustomizeFormatter
{
    /**
     * Customize the given logger instance.
     *
     * @param  \Illuminate\Log\Logger  $logger
     * @return void
     */
    public function __invoke($logger)
    {
        foreach ($logger->getHandlers() as $handler) {
            $handler->setFormatter(...);
        }
    }
}

Все ваши классы «tap» разрешаются контейнером службы , поэтому любые зависимости от конструкторов, которые им требуются, будут автоматически вставлены.

 

Создание каналов обработчика Monolog

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

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

'logentries' => [
    'driver'  => 'monolog',
    'handler' => Monolog\Handler\SyslogUdpHandler::class,
    'with' => [
        'host' => 'my.logentries.internal.datahubhost.company.com',
        'port' => '10000',
    ],
],

Монолог Форматеры

При использовании monologдрайвера Monolog LineFormatterбудет использоваться в качестве форматера по умолчанию. Однако вы можете настроить тип форматера, передаваемого обработчику, используя параметры конфигурации formatterи formatter_with:

'browser' => [
    'driver' => 'monolog',
    'handler' => Monolog\Handler\BrowserConsoleHandler::class,
    'formatter' => Monolog\Formatter\HtmlFormatter::class,
    'formatter_with' => [
        'dateFormat' => 'Y-m-d',
    ],
],

Если вы используете обработчик Monolog, который может предоставить свой собственный модуль форматирования, вы можете установить значение параметра formatterконфигурации в default:

'newrelic' => [
    'driver' => 'monolog',
    'handler' => Monolog\Handler\NewRelicHandler::class,
    'formatter' => 'default',
],

 

Создание каналов через фабрики

Если вы хотите определить полностью собственный канал, в котором вы имеете полный контроль над созданием и настройкой Monolog, вы можете указать customтип драйвера в вашем файле конфигурации. Ваша конфигурация должна включать опцию, указывающую на класс фабрики, который будет вызываться для создания экземпляра Monolog:config/logging.phpvia

'channels' => [
    'custom' => [
        'driver' => 'custom',
        'via' => App\Logging\CreateCustomLogger::class,
    ],
],

После того как вы настроили customканал, вы готовы определить класс, который будет создавать ваш экземпляр Monolog. Этому классу нужен только один метод:, __invokeкоторый должен возвращать экземпляр Monolog:

<?php

namespace App\Logging;

use Monolog\Logger;

class CreateCustomLogger
{
    /**
     * Create a custom Monolog instance.
     *
     * @param  array  $config
     * @return \Monolog\Logger
     */
    public function __invoke(array $config)
    {
        return new Logger(...);
    }
}