后盾人

基础功能

Laravel 5.7 中文文档 / 日志

# 日志

## 介绍

为了帮助您了解应用程序中发生的更多信息，Laravel提供了强大的日志记录服务，允许您将消息记录到文件，系统错误日志，甚至Slack以通知整个团队。

引擎盖下，Laravel利用[Monolog](https://github.com/Seldaek/monolog)库，它提供了多种强大的日志处理程序的支持。Laravel使配置这些处理程序变得简单，允许您混合和匹配它们以自定义应用程序的日志处理。

## 配置

应用程序日志记录系统的所有配置都位于`config/logging.php`配置文件中。此文件允许您配置应用程序的日志通道，因此请务必查看每个可用的通道及其选项。当然，我们将在下面回顾一些常见选项。

默认情况下，Laravel将`stack`在记录消息时使用该通道。该`stack`通道用于将多个日志通道聚合为单个通道。有关构建堆栈的更多信息，请查看以下[文档](https://laravel.com/docs/5.7/logging#building-log-stacks)。

### 配置通道名称

默认情况下，Monolog使用与当前环境匹配的“通道名称”进行实例化，例如`production`或`local`。要更改此值，需添加一个 `name` 选项到你的通道配置中：

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

### 可用的通道驱动

| 名称       | 描述                                                         |
| ---------- | ------------------------------------------------------------ |
| `single`   | 一个便于创建『多通道』通道的包装器                           |
| `daily`    | 单个文件或者基于日志通道的路径 (`StreamHandler`)             |
| `slack`    | 一个每天轮换的基于 Monolog 驱动的 `RotatingFileHandler`      |
| `syslog`   | 一个基于 Monolog 驱动的 `SyslogHandler`                      |
| `errorlog` | 一个基于 Monolog 驱动的 `ErrorLogHandler`                    |
| `monolog`  | 一个可以使用任何支持 Monolog 处理程序的 Monolog 工厂驱动程序 |
| `custom`   | 一个调用指定工厂创建通道的驱动程序                           |

> 查看有关[高级频道自定义](https://laravel.com/docs/5.7/logging#advanced-monolog-channel-customization)的文档，以了解有关`monolog`和`custom`驱动程序的更多信息。

### 配置Slack通道

该`slack`频道需要`url`配置选项。此URL应与您为Slack团队配置的[incoming webhook](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks)的URL匹配。

### 建立日志堆栈

如前所述，`stack`驱动程序允许您将多个通道组合到一个日志通道中。为了说明如何使用日志堆栈，让我们看一下您可能在生产应用程序中看到的示例配置：

```php
'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规范中](https://tools.ietf.org/html/rfc5424)定义的所有日志级别：**emergency**，**alert**，**critical**，**error**，**warning**，**notice**，**info** 和 **debug**。

因此，假设我们使用以下`debug`方法记录消息：

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

根据我们的配置，`syslog`通道会将消息写入系统日志; 但是，由于错误消息不是`critical`或超过，它将不会被发送到Slack。但是，如果我们记录一条`emergency`消息，它将被发送到系统日志和Slack，因为该`emergency`级别高于我们对两个通道的最低级别阈值：

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

## 编写日志消息

您可以使用`Log` [外观](https://laravel.com/docs/5.7/facades)将信息写入日志。如前所述，记录器提供[RFC 5424规范中](https://tools.ietf.org/html/rfc5424)定义的八个日志记录级别：**emergency**, **alert**, **critical**, **error**, **warning**, **notice**, **info** 和 **debug**：

```php
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
<?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)]);
    }
}
```

### 上下文信息

还可以将一组上下文数组数据传递给日志方法。这个上下文数据将被格式化并用日志消息显示：

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

### 写入特定频道

有时您可能希望将消息记录到应用程序默认频道以外的频道。您可以使用Facade `channel`上的方法`Log`来检索并记录配置文件中定义的任何通道：

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

如果要创建由多个通道组成的按需日志记录堆栈，可以使用以下`stack`方法：

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

## 高级Monolog频道定制

### 自定义 Monolog 日志通道

有时你可能需要完全配置 Monolog 现有的通道。例如：你想要为现有通道自定义一个 Monolog `FormatterInterface` 实现。

首先，在频道配置文件中定义一个 `tap` 数组。`tap` 数组应该包含所需的类列表，这些类就是 Monolog 实例创建后需要自定义（或开发）的类：

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

当你完成了通道中 `tap` 选项的配置，你就可以开始写 Monolog 实例自定义类了。这个类只需要一个方法： `__invoke`，这个方法可以接收一个 `Illuminate\Log\Logger` 实例。 `Illuminate\Log\Logger` 实例代理了所有 Monolog 实例底层方法调用：

```php
<?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”类都由[服务容器](https://laravel.com/docs/5.7/container)解析，因此将自动注入它们所需的任何构造函数依赖项。

### 创建自定义通道

Monolog有各种各样的[处理程序](https://github.com/Seldaek/monolog/tree/master/src/Monolog/Handler)。在某些情况下，您希望创建的记录器类型仅仅是具有特定处理程序实例的Monolog驱动程序。可以使用`monolog`驱动程序创建这些通道。

使用`monolog`驱动程序时，`handler`配置选项用于指定将实例化哪个处理程序。（可选）可以使用`handler_with`配置选项指定处理程序所需的任何构造函数参数：

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

#### Monolog Formatters

使用`monolog`驱动程序时，Monolog `LineFormatter`将用作默认格式化程序。但是，您可以使用`formatter`和`formatter_with`配置选项自定义传递给处理程序的格式化程序的类型：

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

如果您使用能够提供自己的格式化程序的Monolog处理程序，则可以将`formatter`配置选项的值设置为`default`：

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

### 通过工厂创建渠道

如果你想定义一个完全自定义的通道，你可以完全控制 Monolog 的实例化和配置，你可以在 `config / logging.php`配置文件中指定 `custom` 驱动程序类型。 你的配置应该包含一个 `via` 选项，指向将被调用以创建 Monolog 实例的工厂类：

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

配置完`custom`通道后，您就可以定义将创建Monolog实例的类。这个类只需要一个方法：`__invoke`，它应该返回Monolog实例：

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