日志记录

• 介绍
• 配置
  • 构建日志堆栈
• 编写日志消息
  • 写入特定通道
• 高级 Monolog 通道自定义
  • 为通道自定义 Monolog
  • 创建 Monolog 处理程序通道
  • 通过工厂创建通道

介绍

为了帮助您更好地了解应用程序内部发生的事情，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 的 Monolog 驱动程序，每日轮换
slack	基于 SlackWebhookHandler 的 Monolog 驱动程序
papertrail	基于 SyslogUdpHandler 的 Monolog 驱动程序
syslog	基于 SyslogHandler 的 Monolog 驱动程序
errorlog	基于 ErrorLogHandler 的 Monolog 驱动程序
monolog	可以使用任何支持的 Monolog 处理程序的 Monolog 工厂驱动程序
custom	调用指定工厂以创建通道的驱动程序

查看高级通道自定义文档以了解有关 monolog 和 custom 驱动程序的更多信息。

配置单通道和每日通道

single 和 daily 通道有三个可选配置选项：bubble、permission 和 locking。

名称	描述	默认值
bubble	指示消息在处理后是否应向其他通道冒泡	true
permission	日志文件的权限	0644
locking	在写入之前尝试锁定日志文件	false

配置 Papertrail 通道

papertrail 通道需要 url 和 port 配置选项。您可以从 Papertrail 获取这些值。

配置 Slack 通道

slack 通道需要一个 url 配置选项。此 URL 应与您为 Slack 团队配置的传入 webhook的 URL 匹配。默认情况下，Slack 只会接收 critical 级别及以上的日志；不过，您可以在 logging 配置文件中进行调整。

构建日志堆栈

如前所述，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 通道配置中存在的 level 配置选项。此选项确定消息必须达到的最低“级别”才能被通道记录。为 Laravel 的日志服务提供支持的 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 facade 将信息写入日志。如前所述，记录器提供了 RFC 5424 规范中定义的八个日志级别：emergency、alert、critical、error、warning、notice、info 和 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 配置文件中配置的默认日志通道：

<?php

namespace App\Http\Controllers;

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

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

上下文信息

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

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

写入特定通道

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

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

如果您希望创建一个由多个通道组成的按需日志堆栈，可以使用 stack 方法：

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

高级 Monolog 通道自定义

为通道自定义 Monolog

有时您可能需要完全控制 Monolog 如何为现有通道配置。例如，您可能希望为给定通道的处理程序配置自定义 Monolog FormatterInterface 实现。

要开始，请在通道的配置中定义一个 tap 数组。tap 数组应包含一个类列表，这些类应有机会在 Monolog 实例创建后自定义（或“tap”）它：

'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

namespace App\Logging;

class CustomizeFormatter
{
    /**
     * 自定义给定的记录器实例。
     *
     * @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 驱动程序时，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 的实例化和配置，您可以在 config/logging.php 配置文件中指定一个 custom 驱动程序类型。您的配置应包括一个 via 选项，以指向将被调用以创建 Monolog 实例的工厂类：

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

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

<?php

namespace App\Logging;

use Monolog\Logger;

class CreateCustomLogger
{
    /**
     * 创建一个自定义的 Monolog 实例。
     *
     * @param  array  $config
     * @return \Monolog\Logger
     */
    public function __invoke(array $config)
    {
        return new Logger(...);
    }
}