Ведение журнала

Введение

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

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

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

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

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

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

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

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

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

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

Каналы single и daily имеют 3 опции конфигурации: bubble, permission, и locking.

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

Канал papertrail требует опции конфигурации url и port. Эти значения можно получить из Papertrail.

Настрока канала Slack

Канал 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. Таким образом, при записи сообщений, оба этих канала будут иметь возможность записывать сообщение.

Уровни записи

Заметьте, что опция конфигурации присутсвует в настройках канала syslog и slack в примере выше. Эта опция определяет минимальный "уровень" сообщения для записи каналом. Monolog уже включает все уровни сообщений в соответствии со спецификацией RFC 5424: emergency, alert, critical, error, warning, notice, info, и debug.

Давайте представим, что мы ведём запись журнала используя метод debug:

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

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

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

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

Вы можете записывать сообщение в журнал используя фасад Log. Как упоминалось ранее, включены 8 уровней сообщений, согласно спецификации в RFC 5424: emergency, alert, critical, error, warning, notice, info and debug:

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 конфигурации:

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 настраивает текущий канал. Например, вы можете настроить пользовательскую реализацию FormatterInterface для данных обработчиков канала.

Чтобы начать, определите массив tap в конфигурации канала. Этот массив содержит список классов, у который должна быть возможность настраивать экземпляр Monolog после создания:

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

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

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(...);
        }
    }
}

Создание обработчика журнала канала

У 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, который может предоставить собственного форматировщика, вы можете установить значение default для опции конфигурации formatter:

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

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

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

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

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

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(...);
    }
}