Laravel error log

1. 1. Введение
2. 2. Настройка
   1. 2.1. Детализация ошибок
   2. 2.2. Хранилище журналов
   3. 2.3. Уровни важности событий
3. 3. Обработчик исключений
   1. 3.1. Метод PHPreport()
   2. 3.2. Метод PHPrender()
4. 4. HTTP-исключения
   1. 4.1. Свои страницы HTTP-ошибок
5. 5. Журналы

Введение

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

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

Настройка

Детализация ошибок

Параметр confdebug в файле настроек config/app.php определяет, сколько информации об ошибке показывать пользователю. По умолчанию этот параметр установлен в соответствии со значением переменной среды APP_DEBUG, которая хранится в файле .env.

Для локальной разработки вам следует установить переменную среды APP_DEBUG в значение true. В продакшн-среде эта переменная всегда должна иметь значение false. Если значение равно true на продакшн-сервере, вы рискуете раскрыть важные значения настроек вашим конечным пользователям.

Хранилище журналов

Изначально Laravel поддерживает запись журналов в единый файл (single), в отдельные файлы за каждый день (daily), в syslog и errorlog. Для использования определённого механизма хранения вам надо изменить параметр conflog в файле config/app.php. Например, если вы хотите использовать ежедневные файлы журнала вместо единого файла, вам надо установить значение log равное daily в файле настроек app:

conf'log_level' => env('APP_LOG_LEVEL', 'error'),

Изменение настроек Monolog

Если вы хотите иметь полный контроль над конфигурацией Monolog для вашего приложения, вы можете использовать метод приложения PHPconfigureMonologUsing(). Вызов этого метода необходимо поместить в файл bootstrap/app.php прямо перед тем, как в нём возвращается переменная PHP$app:

$app->configureMonologUsing(function ($monolog) {
  $monolog->pushHandler(...);
});
return $app;

Обработчик исключений

Метод PHPreport()

Все исключения обрабатываются классом AppExceptionsHandler. Этот класс содержит два метода: PHPreport() и PHPrender(). Рассмотрим каждый из них подробнее. Метод PHPreport() используется для занесения исключений в журнал или для отправки их во внешний сервис, такой как BugSnag или Sentry. По умолчанию метод PHPreport() просто передаёт исключение в базовую реализацию родительского класса, где это исключение зафиксировано. Но вы можете регистрировать исключения как пожелаете.

Например, если вам необходимо сообщать о различных типах исключений разными способами, вы можете использовать оператор сравнения PHP PHPinstanceof::

/**
 * Сообщить или зарегистрировать исключение.
 *
 * Это отличное место для отправки исключений в Sentry, Bugsnag, и т.д.
 *
 * @param  Exception  $exception
 * @return void
 */
public function report(Exception $exception)
{
  if ($exception instanceof CustomException) {
    //
  }
  return 



  


                       
  



parent::report($exception);
}

Игнорирование исключений заданного типа

Свойство обработчика исключений PHP$dontReport содержит массив с типами исключений, которые не будут заноситься в журнал. Например, исключения, возникающие при ошибке 404, а также при некоторых других типах ошибок, не записываются в журналы. При необходимости вы можете включить другие типы исключений в этот массив:

/**
 * Список типов исключений, о которых не надо сообщать.
 *
 * @var array
 */
protected $dontReport = [
  IlluminateAuthAuthenticationException::class,
  IlluminateAuthAccessAuthorizationException::class,
  SymfonyComponentHttpKernelExceptionHttpException::class,
  IlluminateDatabaseEloquentModelNotFoundException::class,
  IlluminateValidationValidationException::class,
];

Метод PHPrender()

Метод PHPrender() отвечает за конвертацию исключения в HTTP-отклик, который должен быть возвращён браузеру. По умолчанию исключение передаётся в базовый класс, который генерирует для вас отклик. Но вы можете проверить тип исключения или вернуть ваш собственный отклик:

/**
 * Отрисовка HTTP-оклика для исключения.
 *
 * @param  IlluminateHttpRequest  $request
 * @param  Exception  $exception
 * @return IlluminateHttpResponse
 */
public function render($request, Exception $exception)
{
  if ($exception instanceof CustomException) {
    return response()->view('errors.custom', [], 500);
  }
  return parent::render($request, $exception);
}

HTTP-исключения

Некоторые исключения описывают коды HTTP-ошибок от сервера. Например, это может быть ошибка «страница не найдена» (404), «ошибка авторизации» (401) или даже сгенерированная разработчиком ошибка 500. Для возврата такого отклика из любого места в приложении можете использовать вспомогательный метод PHPabort():

Вспомогательный метод PHPabort() немедленно создаёт исключение, которое будет отрисовано обработчиком исключений. Или вы можете предоставить такой отклик:

abort(403, 'Unauthorized action.');

Свои страницы HTTP-ошибок

В Laravel можно легко возвращать свои собственные страницы для различных кодов HTTP-ошибок. Например, для выдачи собственной страницы для ошибки 404 создайте файл resources/views/errors/404.blade.php. Этот файл будет использован для всех ошибок 404, генерируемых вашим приложением. Представления в этой папке должны иметь имена, соответствующие кодам ошибок. Экземпляр HttpException, созданный функцией PHPabort(), будет передан в представление как переменная PHP$exception.

Журналы

Laravel обеспечивает простой простой уровень абстракции над мощной библиотекой Monolog. По умолчанию Laravel настроен на создание файла журнала в storage/logs. Вы можете записывать информацию в журнал при помощи фасада Log:

<?phpnamespace AppHttpControllers;
use IlluminateSupportFacadesLog;
//для версии 5.2 и ранее:
//use Log;
use AppUser;
use AppHttpControllersController;
class UserController extends Controller
{
  /**
   * Показать профиль данного пользователя.
   *
   * @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)]);
  }
}

Регистратор событий предоставляет восемь уровней журналирования, описанных в RFC 5424: debug, info, notice, warning, error, critical, alert и emergency.

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

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

Также в методы журналирования может быть передан массив контекстных данных:

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

Обращение к низкоуровневому экземпляру Monolog

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

$monolog = Log::getMonolog();

Log::listen(function($level, $message, $context)
{
  //
});

Logging

• Introduction
• Configuration
  • Available Channel Drivers
  • Channel Prerequisites
  • Logging Deprecation Warnings
• Building Log Stacks
• Writing Log Messages
  • Contextual Information
  • Writing To Specific Channels
• Monolog Channel Customization
  • Customizing Monolog For Channels
  • Creating Monolog Handler Channels
  • Creating Custom Channels Via Factories

Introduction

To help you learn more about what’s happening within your application, Laravel provides robust logging services that allow you to log messages to files, the system error log, and even to Slack to notify your entire team.

Laravel logging is based on «channels». Each channel represents a specific way of writing log information. For example, the single channel writes log files to a single log file, while the slack channel sends log messages to Slack. Log messages may be written to multiple channels based on their severity.

Under the hood, Laravel utilizes the Monolog library, which provides support for a variety of powerful log handlers. Laravel makes it a cinch to configure these handlers, allowing you to mix and match them to customize your application’s log handling.

Configuration

All of the configuration options for your application’s logging behavior is housed in the config/logging.php configuration file. This file allows you to configure your application’s log channels, so be sure to review each of the available channels and their options. We’ll review a few common options below.

By default, Laravel will use the stack channel when logging messages. The stack channel is used to aggregate multiple log channels into a single channel. For more information on building stacks, check out the documentation below.

Configuring The Channel Name

By default, Monolog is instantiated with a «channel name» that matches the current environment, such as production or local. To change this value, add a name option to your channel’s configuration:

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

Available Channel Drivers

Each log channel is powered by a «driver». The driver determines how and where the log message is actually recorded. The following log channel drivers are available in every Laravel application. An entry for most of these drivers is already present in your application’s config/logging.php configuration file, so be sure to review this file to become familiar with its contents:

Note
Check out the documentation on advanced channel customization to learn more about the monolog and custom drivers.

Channel Prerequisites

Configuring The Single and Daily Channels

The single and daily channels have three optional configuration options: bubble, permission, and locking.

Additionally, the retention policy for the daily channel can be configured via the days option:

Configuring The Papertrail Channel

The papertrail channel requires the host and port configuration options. You can obtain these values from Papertrail.

Configuring The Slack Channel

The slack channel requires a url configuration option. This URL should match a URL for an incoming webhook that you have configured for your Slack team.

By default, Slack will only receive logs at the critical level and above; however, you can adjust this in your config/logging.php configuration file by modifying the level configuration option within your Slack log channel’s configuration array.

Logging Deprecation Warnings

PHP, Laravel, and other libraries often notify their users that some of their features have been deprecated and will be removed in a future version. If you would like to log these deprecation warnings, you may specify your preferred deprecations log channel in your application’s config/logging.php configuration file:

'deprecations' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),

'channels' => [
    ...
]

Or, you may define a log channel named deprecations. If a log channel with this name exists, it will always be used to log deprecations:

'channels' => [
    'deprecations' => [
        'driver' => 'single',
        'path' => storage_path('logs/php-deprecation-warnings.log'),
    ],
],

Building Log Stacks

As mentioned previously, the stack driver allows you to combine multiple channels into a single log channel for convenience. To illustrate how to use log stacks, let’s take a look at an example configuration that you might see in a production application:

'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',
    ],
],

Let’s dissect this configuration. First, notice our stack channel aggregates two other channels via its channels option: syslog and slack. So, when logging messages, both of these channels will have the opportunity to log the message. However, as we will see below, whether these channels actually log the message may be determined by the message’s severity / «level».

Log Levels

Take note of the level configuration option present on the syslog and slack channel configurations in the example above. This option determines the minimum «level» a message must be in order to be logged by the channel. Monolog, which powers Laravel’s logging services, offers all of the log levels defined in the RFC 5424 specification. In descending order of severity, these log levels are: emergency, alert, critical, error, warning, notice, info, and debug.

So, imagine we log a message using the debug method:

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

Given our configuration, the syslog channel will write the message to the system log; however, since the error message is not critical or above, it will not be sent to Slack. However, if we log an emergency message, it will be sent to both the system log and Slack since the emergency level is above our minimum level threshold for both channels:

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

Writing Log Messages

You may write information to the logs using the Log facade. As previously mentioned, the logger provides the eight logging levels defined in the RFC 5424 specification: emergency, alert, critical, error, warning, notice, info and debug:

use IlluminateSupportFacadesLog;

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

You may call any of these methods to log a message for the corresponding level. By default, the message will be written to the default log channel as configured by your logging configuration file:

<?php

namespace AppHttpControllers;

use AppHttpControllersController;
use AppModelsUser;
use IlluminateSupportFacadesLog;

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

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

Contextual Information

An array of contextual data may be passed to the log methods. This contextual data will be formatted and displayed with the log message:

use IlluminateSupportFacadesLog;

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

Occasionally, you may wish to specify some contextual information that should be included with all subsequent log entries in a particular channel. For example, you may wish to log a request ID that is associated with each incoming request to your application. To accomplish this, you may call the Log facade’s withContext method:

<?php

namespace AppHttpMiddleware;

use Closure;
use IlluminateSupportFacadesLog;
use IlluminateSupportStr;

class AssignRequestId
{
    /**
     * Handle an incoming request.
     *
     * @param  IlluminateHttpRequest  $request
     * @param  Closure  $next
     * @return mixed
     */
    public function handle($request, Closure $next)
    {
        $requestId = (string) Str::uuid();

        Log::withContext([
            'request-id' => $requestId
        ]);

        return $next($request)->header('Request-Id', $requestId);
    }
}

If you would like to share contextual information across all logging channels, you may call the Log::shareContext() method. This method will provide the contextual information to all created channels and any channels that are created subsequently. Typically, the shareContext method should be called from the boot method of an application service provider:

use IlluminateSupportFacadesLog;
use IlluminateSupportStr;

class AppServiceProvider
{
    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        Log::shareContext([
            'invocation-id' => (string) Str::uuid(),
        ]);
    }
}

Writing To Specific Channels

Sometimes you may wish to log a message to a channel other than your application’s default channel. You may use the channel method on the Log facade to retrieve and log to any channel defined in your configuration file:

use IlluminateSupportFacadesLog;

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

If you would like to create an on-demand logging stack consisting of multiple channels, you may use the stack method:

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

On-Demand Channels

It is also possible to create an on-demand channel by providing the configuration at runtime without that configuration being present in your application’s logging configuration file. To accomplish this, you may pass a configuration array to the Log facade’s build method:

use IlluminateSupportFacadesLog;

Log::build([
  'driver' => 'single',
  'path' => storage_path('logs/custom.log'),
])->info('Something happened!');

You may also wish to include an on-demand channel in an on-demand logging stack. This can be achieved by including your on-demand channel instance in the array passed to the stack method:

use IlluminateSupportFacadesLog;

$channel = Log::build([
  'driver' => 'single',
  'path' => storage_path('logs/custom.log'),
]);

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

Monolog Channel Customization

Customizing Monolog For Channels

Sometimes you may need complete control over how Monolog is configured for an existing channel. For example, you may want to configure a custom Monolog FormatterInterface implementation for Laravel’s built-in single channel.

To get started, define a tap array on the channel’s configuration. The tap array should contain a list of classes that should have an opportunity to customize (or «tap» into) the Monolog instance after it is created. There is no conventional location where these classes should be placed, so you are free to create a directory within your application to contain these classes:

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

Once you have configured the tap option on your channel, you’re ready to define the class that will customize your Monolog instance. This class only needs a single method: __invoke, which receives an IlluminateLogLogger instance. The IlluminateLogLogger instance proxies all method calls to the underlying Monolog instance:

<?php

namespace AppLogging;

use MonologFormatterLineFormatter;

class CustomizeFormatter
{
    /**
     * Customize the given logger instance.
     *
     * @param  IlluminateLogLogger  $logger
     * @return void
     */
    public function __invoke($logger)
    {
        foreach ($logger->getHandlers() as $handler) {
            $handler->setFormatter(new LineFormatter(
                '[%datetime%] %channel%.%level_name%: %message% %context% %extra%'
            ));
        }
    }
}

Note
All of your «tap» classes are resolved by the service container, so any constructor dependencies they require will automatically be injected.

Creating Monolog Handler Channels

Monolog has a variety of available handlers and Laravel does not include a built-in channel for each one. In some cases, you may wish to create a custom channel that is merely an instance of a specific Monolog handler that does not have a corresponding Laravel log driver. These channels can be easily created using the monolog driver.

When using the monolog driver, the handler configuration option is used to specify which handler will be instantiated. Optionally, any constructor parameters the handler needs may be specified using the with configuration option:

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

Monolog Formatters

When using the monolog driver, the Monolog LineFormatter will be used as the default formatter. However, you may customize the type of formatter passed to the handler using the formatter and formatter_with configuration options:

'browser' => [
    'driver' => 'monolog',
    'handler' => MonologHandlerBrowserConsoleHandler::class,
    'formatter' => MonologFormatterHtmlFormatter::class,
    'formatter_with' => [
        'dateFormat' => 'Y-m-d',
    ],
],

If you are using a Monolog handler that is capable of providing its own formatter, you may set the value of the formatter configuration option to default:

'newrelic' => [
    'driver' => 'monolog',
    'handler' => MonologHandlerNewRelicHandler::class,
    'formatter' => 'default',
],

Creating Custom Channels Via Factories

If you would like to define an entirely custom channel in which you have full control over Monolog’s instantiation and configuration, you may specify a custom driver type in your config/logging.php configuration file. Your configuration should include a via option that contains the name of the factory class which will be invoked to create the Monolog instance:

'channels' => [
    'example-custom-channel' => [
        'driver' => 'custom',
        'via' => AppLoggingCreateCustomLogger::class,
    ],
],

Once you have configured the custom driver channel, you’re ready to define the class that will create your Monolog instance. This class only needs a single __invoke method which should return the Monolog logger instance. The method will receive the channels configuration array as its only argument:

<?php

namespace AppLogging;

use MonologLogger;

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

• Configuration
• Handling Errors
• HTTP Exceptions
• Logging

Configuration

The logging facilities for your application are configured in the IlluminateFoundationBootstrapConfigureLogging bootstrapper class. This class utilizes the log configuration option from your config/app.php configuration file.

By default, the logger is configured to use daily log files; however, you may customize this behavior as needed. Since Laravel uses the popular Monolog logging library, you can take advantage of the variety of handlers that Monolog offers.

For example, if you wish to use a single log file instead of daily files, you can make the following change to your config/app.php configuration file:

'log' => 'single'

Out of the box, Laravel supported single, daily, syslog and errorlog logging modes. However, you are free to customize the logging for your application as you wish by overriding the ConfigureLogging bootstrapper class.

Error Detail

The amount of error detail your application displays through the browser is controlled by the app.debug configuration option in your config/app.php configuration file. By default, this configuration option is set to respect the APP_DEBUG environment variable, which is stored in your .env file.

For local development, you should set the APP_DEBUG environment variable to true. In your production environment, this value should always be false.

Handling Errors

All exceptions are handled by the AppExceptionsHandler class. This class contains two methods: report and render.

The report method is used to log exceptions or send them to an external service like BugSnag. By default, the report method simply passes the exception to the base implementation on the parent class where the exception is logged. However, you are free to log exceptions however you wish. If you need to report different types of exceptions in different ways, you may use the PHP instanceof comparison operator:

/**
 * Report or log an exception.
 *
 * This is a great spot to send exceptions to Sentry, Bugsnag, etc.
 *
 * @param  Exception  $e
 * @return void
 */
public function report(Exception $e)
{
    if ($e instanceof CustomException)
    {
        //
    }

    return parent::report($e);
}

The render method is responsible for converting the exception into an HTTP response that should be sent back to the browser. By default, the exception is passed to the base class which generates a response for you. However, you are free to check the exception type or return your own custom response.

The dontReport property of the exception handler contains an array of exception types that will not be logged. By default, exceptions resulting from 404 errors are not written to your log files. You may add other exception types to this array as needed.

HTTP Exceptions

Some exceptions describe HTTP error codes from the server. For example, this may be a «page not found» error (404), an «unauthorized error» (401) or even a developer generated 500 error. In order to return such a response, use the following:

abort(404);

Optionally, you may provide a response:

abort(403, 'Unauthorized action.');

This method may be used at any time during the request’s lifecycle.

Custom 404 Error Page

To return a custom view for all 404 errors, create a resources/views/errors/404.blade.php file. This view will be served on all 404 errors generated by your application.

Logging

The Laravel logging facilities provide a simple layer on top of the powerful Monolog library. By default, Laravel is configured to create daily log files for your application which are stored in the storage/logs directory. You may write information to the log like so:

Log::info('This is some useful information.');

Log::warning('Something could be going wrong.');

Log::error('Something is really going wrong.');

The logger provides the seven logging levels defined in RFC 5424: debug, info, notice, warning, error, critical, and alert.

An array of contextual data may also be passed to the log methods:

Log::info('Log message', ['context' => 'Other helpful information']);

Monolog has a variety of additional handlers you may use for logging. If needed, you may access the underlying Monolog instance being used by Laravel:

$monolog = Log::getMonolog();

You may also register an event to catch all messages passed to the log:

Registering A Log Event Listener

Log::listen(function($level, $message, $context)
{
    //
});