starting logging docs
This commit is contained in:
Taylor Otwell
parent
cb7b1ba8e4
commit
1efdd3af78
|
|
@ -27,7 +27,8 @@
|
|||
- [URL Generation](/docs/{{version}}/urls)
|
||||
- [Session](/docs/{{version}}/session)
|
||||
- [Validation](/docs/{{version}}/validation)
|
||||
- [Errors & Logging](/docs/{{version}}/errors)
|
||||
- [Error Handling](/docs/{{version}}/errors)
|
||||
- [Logging](/docs/{{version}}/logging)
|
||||
- ## Frontend
|
||||
- [Blade Templates](/docs/{{version}}/blade)
|
||||
- [Localization](/docs/{{version}}/localization)
|
||||
|
|
|
|||
107
errors.md
107
errors.md
|
|
@ -1,77 +1,26 @@
|
|||
# Errors & Logging
|
||||
# Error Handling
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [Configuration](#configuration)
|
||||
- [Error Detail](#error-detail)
|
||||
- [Log Storage](#log-storage)
|
||||
- [Log Severity Levels](#log-severity-levels)
|
||||
- [Custom Monolog Configuration](#custom-monolog-configuration)
|
||||
- [The Exception Handler](#the-exception-handler)
|
||||
- [Report Method](#report-method)
|
||||
- [Render Method](#render-method)
|
||||
- [Reportable & Renderable Exceptions](#renderable-exceptions)
|
||||
- [HTTP Exceptions](#http-exceptions)
|
||||
- [Custom HTTP Error Pages](#custom-http-error-pages)
|
||||
- [Logging](#logging)
|
||||
|
||||
<a name="introduction"></a>
|
||||
## Introduction
|
||||
|
||||
When you start a new Laravel project, error and exception handling is already configured for you. The `App\Exceptions\Handler` class is where all exceptions triggered by your application are logged and then rendered back to the user. We'll dive deeper into this class throughout this documentation.
|
||||
|
||||
For logging, Laravel utilizes the [Monolog](https://github.com/Seldaek/monolog) library, which provides support for a variety of powerful log handlers. Laravel configures several of these handlers for you, allowing you to choose between a single log file, rotating log files, or writing error information to the system log.
|
||||
|
||||
<a name="configuration"></a>
|
||||
## Configuration
|
||||
|
||||
<a name="error-detail"></a>
|
||||
### Error Detail
|
||||
|
||||
The `debug` option in your `config/app.php` configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of 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`. If the value is set to `true` in production, you risk exposing sensitive configuration values to your application's end users.
|
||||
|
||||
<a name="log-storage"></a>
|
||||
### Log Storage
|
||||
|
||||
Out of the box, Laravel supports writing log information to `single` files, `daily` files, the `syslog`, and the `errorlog`. To configure which storage mechanism Laravel uses, you should modify the `log` option in your `config/app.php` configuration file. For example, if you wish to use daily log files instead of a single file, you should set the `log` value in your `app` configuration file to `daily`:
|
||||
|
||||
'log' => 'daily'
|
||||
|
||||
#### Maximum Daily Log Files
|
||||
|
||||
When using the `daily` log mode, Laravel will only retain five days of log files by default. If you want to adjust the number of retained files, you may add a `log_max_files` configuration value to your `app` configuration file:
|
||||
|
||||
'log_max_files' => 30
|
||||
|
||||
<a name="log-severity-levels"></a>
|
||||
### Log Severity Levels
|
||||
|
||||
When using Monolog, log messages may have different levels of severity. By default, Laravel writes all log levels to storage. However, in your production environment, you may wish to configure the minimum severity that should be logged by adding the `log_level` option to your `app.php` configuration file.
|
||||
|
||||
Once this option has been configured, Laravel will log all levels greater than or equal to the specified severity. For example, a default `log_level` of `error` will log **error**, **critical**, **alert**, and **emergency** messages:
|
||||
|
||||
'log_level' => env('APP_LOG_LEVEL', 'error'),
|
||||
|
||||
> {tip} Monolog recognizes the following severity levels - from least severe to most severe: `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`.
|
||||
|
||||
<a name="custom-monolog-configuration"></a>
|
||||
### Custom Monolog Configuration
|
||||
|
||||
If you would like to have complete control over how Monolog is configured for your application, you may use the application's `configureMonologUsing` method. You should place a call to this method in your `bootstrap/app.php` file right before the `$app` variable is returned by the file:
|
||||
|
||||
$app->configureMonologUsing(function ($monolog) {
|
||||
$monolog->pushHandler(...);
|
||||
});
|
||||
|
||||
return $app;
|
||||
|
||||
#### Customizing The Channel Name
|
||||
|
||||
By default, Monolog is instantiated with name that matches the current environment, such as `production` or `local`. To change this value, add the `log_channel` option to your `app.php` configuration file:
|
||||
|
||||
'log_channel' => env('APP_LOG_CHANNEL', 'my-app-name'),
|
||||
|
||||
<a name="the-exception-handler"></a>
|
||||
## The Exception Handler
|
||||
|
||||
|
|
@ -99,6 +48,8 @@ For example, if you need to report different types of exceptions in different wa
|
|||
return parent::report($exception);
|
||||
}
|
||||
|
||||
> {tip} Instead of making a lot of `instanceof` checks in your `report` method, consider using [reportable exceptions](/docs/{{version}}/errors#renderable-exceptions)
|
||||
|
||||
#### The `report` Helper
|
||||
|
||||
Sometimes you may need to report an exception but continue handling the current request. The `report` helper function allows you to quickly report an exception using your exception handler's `report` method without rendering an error page:
|
||||
|
|
@ -204,55 +155,3 @@ The `abort` helper will immediately raise an exception which will be rendered by
|
|||
Laravel makes it easy to display custom error pages for various HTTP status codes. For example, if you wish to customize the error page for 404 HTTP status codes, create a `resources/views/errors/404.blade.php`. This file will be served on all 404 errors generated by your application. The views within this directory should be named to match the HTTP status code they correspond to. The `HttpException` instance raised by the `abort` function will be passed to the view as an `$exception` variable:
|
||||
|
||||
<h2>{{ $exception->getMessage() }}</h2>
|
||||
|
||||
<a name="logging"></a>
|
||||
## Logging
|
||||
|
||||
Laravel provides a simple abstraction layer on top of the powerful [Monolog](https://github.com/seldaek/monolog) library. By default, Laravel is configured to create a log file for your application in the `storage/logs` directory. You may write information to the logs using the `Log` [facade](/docs/{{version}}/facades):
|
||||
|
||||
<?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)]);
|
||||
}
|
||||
}
|
||||
|
||||
The logger provides the eight logging levels defined in [RFC 5424](https://tools.ietf.org/html/rfc5424): **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);
|
||||
|
||||
#### Contextual Information
|
||||
|
||||
An array of contextual data may also be passed to the log methods. This contextual data will be formatted and displayed with the log message:
|
||||
|
||||
Log::info('User failed to login.', ['id' => $user->id]);
|
||||
|
||||
#### Accessing The Underlying Monolog Instance
|
||||
|
||||
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();
|
||||
|
|
|
|||
|
|
@ -0,0 +1,110 @@
|
|||
# Logging
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [Configuration](#configuration)
|
||||
- [Building Log Stacks](#building-log-stacks)
|
||||
- [Customizing Monolog](#customizing-monolog)
|
||||
- [Writing Log Messages](#writing-log-messages)
|
||||
|
||||
<a name="introduction"></a>
|
||||
## Introduction
|
||||
|
||||
To help you learn more of what's happening within your application, Laravel provides robust logging services that allow you to log messages and errors to files, the system error log, or even to Slack to notify your entire team.
|
||||
|
||||
Under the hood, Laravel utilizes the [Monolog](https://github.com/Seldaek/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.
|
||||
|
||||
<a name="configuration"></a>
|
||||
## Configuration
|
||||
|
||||
All of the configuration for your application's logging system 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. Of course, we'll review a few common options below.
|
||||
|
||||
By default, Laravel will use the `stack` channel when logging messages. The `stack` channel type is used to aggregate multiple log handlers into a single channel. For more information on building stacks, check out the [documentation below](#building-log-stacks).
|
||||
|
||||
#### Customizing 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'],
|
||||
],
|
||||
|
||||
<a name="building-log-stacks"></a>
|
||||
### Building Log Stacks
|
||||
|
||||
Here Test
|
||||
|
||||
<a name="log-severity-levels"></a>
|
||||
#### Log Severity Levels
|
||||
|
||||
Log messages may have different levels of severity. By default, Laravel typically writes all log levels to storage. However, in your production environment, you may wish to configure the minimum severity that should be logged.
|
||||
|
||||
Once this option has been configured, Laravel will log all levels greater than or equal to the specified severity. For example, a default `log_level` of `error` will log **error**, **critical**, **alert**, and **emergency** messages:
|
||||
|
||||
'log_level' => env('APP_LOG_LEVEL', 'error'),
|
||||
|
||||
> {tip} Monolog recognizes the following severity levels - from least severe to most severe: `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`.
|
||||
|
||||
<a name="customizing-monolog"></a>
|
||||
### Customizing Monolog
|
||||
|
||||
If you would like to have complete control over how Monolog is configured for your application, you may use the application's `configureMonologUsing` method. You should place a call to this method in your `bootstrap/app.php` file right before the `$app` variable is returned by the file:
|
||||
|
||||
$app->configureMonologUsing(function ($monolog) {
|
||||
$monolog->pushHandler(...);
|
||||
});
|
||||
|
||||
return $app;
|
||||
|
||||
<a name="writing-log-messages"></a>
|
||||
## Writing Log Messages
|
||||
|
||||
Laravel provides a simple abstraction layer on top of the powerful [Monolog](https://github.com/seldaek/monolog) library. By default, Laravel is configured to create a log file for your application in the `storage/logs` directory. You may write information to the logs using the `Log` [facade](/docs/{{version}}/facades):
|
||||
|
||||
<?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)]);
|
||||
}
|
||||
}
|
||||
|
||||
The logger provides the eight logging levels defined in [RFC 5424](https://tools.ietf.org/html/rfc5424): **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);
|
||||
|
||||
#### Contextual Information
|
||||
|
||||
An array of contextual data may also be passed to the log methods. This contextual data will be formatted and displayed with the log message:
|
||||
|
||||
Log::info('User failed to login.', ['id' => $user->id]);
|
||||
|
||||
#### Accessing The Underlying Monolog Instance
|
||||
|
||||
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();
|
||||
Loading…
Reference in New Issue