日志记录

简介

为了帮助你更深入地了解应用程序内部的运行情况，Laravel 提供了强大的日志记录服务，允许你将消息记录到文件、系统错误日志，甚至可以发送到 Slack 以通知你的整个团队。

Laravel 的日志记录基于“通道（channels）”。每个通道代表一种特定的记录日志信息的方式。例如，single 通道会将日志文件写入单个日志文件中，而 slack 通道会将日志消息发送到 Slack。日志消息可以根据其严重程度被写入多个通道。

在底层，Laravel 使用了 Monolog 库，该库支持多种功能强大的日志处理器。Laravel 让配置这些处理器变得易如反掌，允许你根据需要混合搭配它们，以自定义应用程序的日志处理方式。

配置

控制应用程序日志记录行为的所有配置选项都存放在 config/logging.php 配置文件中。此文件允许你配置应用程序的日志通道，因此请务必仔细查看每个可用通道及其选项。我们将在下面介绍一些常见选项。

默认情况下，Laravel 在记录消息时会使用 stack 通道。stack 通道用于将多个日志通道聚合为单个通道。有关构建日志堆栈的更多信息，请参阅下方的文档。

可用的通道驱动

每个日志通道都由一个“驱动（driver）”驱动。驱动决定了日志消息实际记录的方式和位置。以下日志通道驱动在每个 Laravel 应用程序中均可使用。你的应用程序的 config/logging.php 配置文件中已经包含了这些驱动中的大部分条目，因此请务必查看此文件以熟悉其内容：

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

配置通道名称

默认情况下，Monolog 实例化的“通道名称”会与当前环境相匹配，例如 production 或 local。若要更改此值，你可以为通道的配置添加 name 选项：

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

通道前置条件

配置 Single、Daily 和 Monthly 通道

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

此外，daily 和 monthly 通道的保留策略可以通过 max_files 配置选项进行配置。LOG_DAILY_DAYS 环境变量也可用于配置 daily 通道的保留时间。

配置 Papertrail 通道

papertrail 通道需要 host 和 port 配置选项。这些选项可以通过 PAPERTRAIL_URL 和 PAPERTRAIL_PORT 环境变量定义。你可以从 Papertrail 获取这些值。

配置 Slack 通道

slack 通道需要 url 配置选项。此值可以通过 LOG_SLACK_WEBHOOK_URL 环境变量定义。此 URL 应与你为 Slack 团队配置的 传入 Webhook 的 URL 相匹配。

默认情况下，Slack 仅会接收 critical 级别及以上的日志；不过，你可以使用 LOG_LEVEL 环境变量，或通过修改 Slack 日志通道配置数组中的 level 配置选项来调整此设置。

记录弃用警告

PHP、Laravel 及其他库通常会通知用户，其某些功能已被弃用，并将在未来的版本中移除。如果你想记录这些弃用警告，可以通过 LOG_DEPRECATIONS_CHANNEL 环境变量，或在应用程序的 config/logging.php 配置文件中指定你首选的 deprecations 日志通道：

'deprecations' => [
    'channel' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
    'trace' => env('LOG_DEPRECATIONS_TRACE', false),
],

'channels' => [
    // ...
]

或者，你可以定义一个名为 deprecations 的日志通道。如果存在同名的日志通道，则该通道将始终用于记录弃用信息：

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

构建日志堆栈

如前所述，stack 驱动允许你将多个通道组合为单个日志通道，以便使用。为了说明如何使用日志堆栈，我们来看一个在生产环境中可能会看到的配置示例：

'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['syslog', 'slack'],
        'ignore_exceptions' => false,
    ],

    'syslog' => [
        'driver' => 'syslog',
        'level' => env('LOG_LEVEL', 'debug'),
        'facility' => env('LOG_SYSLOG_FACILITY', LOG_USER),
        'replace_placeholders' => true,
    ],

    'slack' => [
        'driver' => 'slack',
        'url' => env('LOG_SLACK_WEBHOOK_URL'),
        'username' => env('LOG_SLACK_USERNAME', 'Laravel Log'),
        'emoji' => env('LOG_SLACK_EMOJI', ':boom:'),
        'level' => env('LOG_LEVEL', 'critical'),
        'replace_placeholders' => true,
    ],
],

让我们来剖析一下这个配置。首先，请注意我们的 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（调试）：

use Illuminate\Support\Facades\Log;

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

您可以调用其中任意方法，为对应的日志级别记录消息。默认情况下，消息会写入由 logging 配置文件所配置的默认日志通道：

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Support\Facades\Log;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * 显示指定用户的个人资料。
     */
    public function show(string $id): View
    {
        Log::info('Showing the user profile for user: {id}', ['id' => $id]);

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

上下文信息

可以向日志方法传递一个上下文数据数组。这些上下文数据会进行格式化，并随日志消息一同显示：

use Illuminate\Support\Facades\Log;

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

有时，您可能希望为特定通道中的所有后续日志记录指定一些上下文信息。例如，您可能希望记录与应用程序每个传入请求相关的请求 ID。要实现这一点，您可以调用 Log 外观类的 withContext 方法：

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;

class AssignRequestId
{
    /**
     * 处理传入的请求。
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        $requestId = (string) Str::uuid();

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

        $response = $next($request);

        $response->headers->set('Request-Id', $requestId);

        return $response;
    }
}

如果您希望在所有日志通道中共享上下文信息，可以调用 Log::shareContext() 方法。该方法会将上下文信息提供给所有已创建的通道以及后续创建的任何通道：

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;

class AssignRequestId
{
    /**
     * 处理传入的请求。
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        $requestId = (string) Str::uuid();

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

        // ...
    }
}

如果在处理队列任务时需要共享日志上下文，可以使用任务中间件。

写入特定通道

有时，您可能希望将消息记录到应用程序默认通道以外的通道。您可以使用 Log 外观类的 channel 方法，来获取并记录到配置文件中定义的任意通道：

use Illuminate\Support\Facades\Log;

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

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

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

按需通道

您还可以在运行时提供配置来创建按需通道，而无需在应用程序的 logging 配置文件中配置该通道。要实现这一点，您可以将配置数组传递给 Log 外观类的 build 方法：

use Illuminate\Support\Facades\Log;

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

您可能还希望将按需通道包含到按需日志堆栈中。这可以通过将按需通道实例包含在传递给 stack 方法的数组中来实现：

use Illuminate\Support\Facades\Log;

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

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

Monolog 通道定制

为通道定制 Monolog

有时，您可能需要完全控制现有通道的 Monolog 配置方式。例如，您可能希望为 Laravel 内置的 single 通道配置自定义的 Monolog FormatterInterface 实现。

首先，在通道配置中定义一个 tap 数组。tap 数组应包含一个类列表，这些类应有机会在 Monolog 实例创建后对其进行定制（或“接入”）。这些类没有固定的存放位置，因此您可以在应用程序中自由创建目录来存放这些类：

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

一旦在通道上配置了 tap 选项，就可以定义用于定制 Monolog 实例的类。该类只需一个方法：__invoke，该方法接收一个 Illuminate\Log\Logger 实例。Illuminate\Log\Logger 实例会将所有方法调用代理到底层 Monolog 实例：

<?php

namespace App\Logging;

use Illuminate\Log\Logger;
use Monolog\Formatter\LineFormatter;

class CustomizeFormatter
{
    /**
     * 定制给定的日志记录器实例。
     */
    public function __invoke(Logger $logger): void
    {
        foreach ($logger->getHandlers() as $handler) {
            $handler->setFormatter(new LineFormatter(
                '[%datetime%] %channel%.%level_name%: %message% %context% %extra%'
            ));
        }
    }
}

所有“tap”类均由服务容器解析，因此它们所需的任何构造函数依赖都会被自动注入。

创建 Monolog 处理器通道

Monolog 拥有多种可用处理器，而 Laravel 并不会为每种处理器都提供内置通道。在某些情况下，您可能希望创建一个自定义通道，该通道仅仅是特定 Monolog 处理器的实例，而该处理器没有对应的 Laravel 日志驱动程序。使用 monolog 驱动程序可以轻松创建这些通道。

当使用 monolog 驱动程序时，handler 配置选项用于指定要实例化的处理器。可选地，处理器所需的任何构造函数参数都可以通过 handler_with 配置选项指定：

'logentries' => [
    'driver'  => 'monolog',
    'handler' => Monolog\Handler\SyslogUdpHandler::class,
    'handler_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 处理器（Processors）

Monolog 还可以在记录日志之前对消息进行处理。你可以创建自己的处理器，也可以使用 Monolog 提供的现有处理器。

如果你想为某个 monolog 驱动自定义处理器，请在你的通道配置中添加 processors 配置项：

'memory' => [
    'driver' => 'monolog',
    'handler' => Monolog\Handler\StreamHandler::class,
    'handler_with' => [
        'stream' => 'php://stderr',
    ],
    'processors' => [
        // 简单语法...
        Monolog\Processor\MemoryUsageProcessor::class,

        // 带选项...
        [
            'processor' => Monolog\Processor\PsrLogMessageProcessor::class,
            'with' => ['removeUsedContextFields' => true],
        ],
    ],
],

通过工厂创建自定义通道

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

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

配置好 custom 驱动通道后，你就可以定义用于创建 Monolog 实例的类了。该类只需包含一个 __invoke 方法，该方法应返回 Monolog 日志记录器实例。该方法将接收通道配置数组作为其唯一参数：

<?php

namespace App\Logging;

use Monolog\Logger;

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

使用 Pail 跟踪日志消息

你经常需要实时跟踪应用程序的日志。例如，在调试问题时，或者在监控应用程序日志以查找特定类型的错误时。

Laravel Pail 是一个包，可让你直接从命令行轻松深入查看 Laravel 应用程序的日志文件。与标准的 tail 命令不同，Pail 支持所有日志驱动，包括 Laravel Nightwatch、Sentry 或 Flare。此外，Pail 还提供了一组实用的过滤器，可帮助你快速找到所需内容。

安装

Laravel Pail 需要 PCNTL PHP 扩展。

若要开始使用，请使用 Composer 包管理器将 Pail 安装到你的项目中：

composer require --dev laravel/pail

用法

要开始跟踪日志，请运行 pail 命令：

php artisan pail

若要提高输出的详细程度并避免截断（…），请使用 -v 选项：

php artisan pail -v

若要获得最高详细程度并显示异常堆栈跟踪，请使用 -vv 选项：

php artisan pail -vv

要停止跟踪日志，随时按下 Ctrl+C。

过滤日志

--filter

你可以使用 --filter 选项，按类型、文件、消息和堆栈跟踪内容来过滤日志：

php artisan pail --filter="QueryException"

--message

若要仅按消息过滤日志，你可以使用 --message 选项：

php artisan pail --message="User created"

--level

可以使用 --level 选项，按日志级别来过滤日志：

php artisan pail --level=error

--user

若要仅显示在指定用户已认证期间写入的日志，你可以向 --user 选项提供该用户的 ID：

php artisan pail --user=1