日志记录

介绍
配置
构建日志堆栈
写入日志消息
- 上下文信息
- 写入特定通道
Monolog 通道自定义
使用 Pail 尾随日志消息

介绍

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

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

在底层，Laravel 利用 Monolog 库，该库支持多种强大的日志处理程序。Laravel 使配置这些处理程序变得简单，允许您混合和匹配它们以自定义应用程序的日志处理。

配置

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

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

可用的通道驱动

每个日志通道由一个“驱动”提供支持。驱动决定日志消息实际记录的方式和位置。每个 Laravel 应用程序中都可用以下日志通道驱动。大多数这些驱动的条目已经存在于您应用程序的 config/logging.php 配置文件中，因此请务必查看该文件以熟悉其内容：

名称	描述
`custom`	一个调用指定工厂以创建通道的驱动。
`daily`	基于 `RotatingFileHandler` 的 Monolog 驱动，每天轮换。
`errorlog`	基于 `ErrorLogHandler` 的 Monolog 驱动。
`monolog`	一个 Monolog 工厂驱动，可以使用任何支持的 Monolog 处理程序。
`papertrail`	基于 `SyslogUdpHandler` 的 Monolog 驱动。
`single`	一个基于单个文件或路径的记录通道（`StreamHandler`）。
`slack`	基于 `SlackWebhookHandler` 的 Monolog 驱动。
`stack`	一个包装器，用于创建“多通道”通道。
`syslog`	基于 `SyslogHandler` 的 Monolog 驱动。

NOTE

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

配置通道名称

默认情况下，Monolog 使用与当前环境匹配的“通道名称”，例如 production 或 local。要更改此值，您可以在通道的配置中添加 name 选项：

php

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

通道先决条件

配置单通道和每日通道

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

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

此外，可以通过 LOG_DAILY_DAYS 环境变量或设置 days 配置选项来配置 daily 通道的保留策略。

名称	描述	默认值
`days`	每日日志文件应保留的天数。	`14`

配置 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 日志通道：

php

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

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

或者，您可以定义一个名为 deprecations 的日志通道。如果存在具有此名称的日志通道，则将始终使用它来记录弃用警告：

php

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

构建日志堆栈

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

php

'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 配置选项。此选项确定消息必须达到的最低“级别”，才能被通道记录。Monolog 为 Laravel 的日志记录服务提供了在 RFC 5424 规范中定义的所有日志级别。按严重性降序排列，这些日志级别为：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 门面将信息写入日志。如前所述，记录器提供了在 RFC 5424 规范中定义的八个日志级别：emergency、alert、critical、error、warning、notice、info 和 debug：

php

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

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
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)
        ]);
    }
}

上下文信息

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

php

use Illuminate\Support\Facades\Log;

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

有时，您可能希望指定一些上下文信息，这些信息应包含在特定通道的所有后续日志条目中。例如，您可能希望记录与每个传入请求相关联的请求 ID。为此，您可以调用 Log 门面的 withContext 方法：

php

<?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

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

        // ...
    }
}

NOTE

如果您需要在处理排队作业时共享日志上下文，可以利用作业中间件。

写入特定通道

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

php

use Illuminate\Support\Facades\Log;

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

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

php

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

按需通道

还可以通过在运行时提供配置来创建按需通道，而该配置不必存在于应用程序的 logging 配置文件中。为此，您可以将配置数组传递给 Log 门面的 build 方法：

php

use Illuminate\Support\Facades\Log;

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

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

php

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 实例后进行自定义（或“点击”）。这些类没有常规位置，因此您可以自由创建一个目录来包含这些类：

php

'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

<?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%'
            ));
        }
    }
}

NOTE

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

创建 Monolog 处理程序通道

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

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

php

'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 配置选项自定义传递给处理程序的格式化器类型：

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 处理器

Monolog 还可以在记录消息之前处理它们。您可以创建自己的处理器或使用 Monolog 提供的现有处理器。

如果您希望自定义 monolog 驱动的处理器，请在通道的配置中添加 processors 配置值：

php

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

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

通过工厂创建自定义通道

如果您希望在完全控制 Monolog 的实例化和配置的情况下定义一个完全自定义的通道，可以在 config/logging.php 配置文件中指定 custom 驱动类型。您的配置应包括一个 via 选项，其中包含将被调用以创建 Monolog 实例的工厂类的名称：

php

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

一旦您配置了 custom 驱动通道，就可以定义将创建 Monolog 实例的类。此类只需要一个 __invoke 方法，该方法应返回 Monolog 记录器实例。该方法将接收通道配置数组作为唯一参数：

php

<?php

namespace App\Logging;

use Monolog\Logger;

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

使用 Pail 尾随日志消息

您可能需要实时尾随应用程序的日志。例如，在调试问题或监控应用程序的日志以查找特定类型的错误时。

Laravel Pail 是一个允许您直接从命令行轻松查看 Laravel 应用程序日志文件的包。与标准的 tail 命令不同，Pail 旨在与任何日志驱动一起使用，包括 Sentry 或 Flare。此外，Pail 提供了一组有用的过滤器，以帮助您快速找到所需内容。

安装

WARNING

Laravel Pail 需要 PHP 8.2+ 和 PCNTL 扩展。

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

bash

composer require laravel/pail

用法

要开始尾随日志，请运行 pail 命令：

bash

php artisan pail

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

bash

php artisan pail -v

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

bash

php artisan pail -vv

要停止尾随日志，请随时按 Ctrl+C。

过滤日志

`--filter`

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

bash

php artisan pail --filter="QueryException"

`--message`

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

bash

php artisan pail --message="User created"

`--level`

--level 选项可用于按其日志级别过滤日志：

bash

php artisan pail --level=error

`--user`

要仅显示在给定用户身份验证期间写入的日志，您可以将用户的 ID 提供给 --user 选项：

bash

php artisan pail --user=1

日志记录 ​

介绍 ​

配置 ​

可用的通道驱动 ​

配置通道名称 ​

通道先决条件 ​

配置单通道和每日通道 ​

配置 Papertrail 通道 ​

配置 Slack 通道 ​

日志记录弃用警告 ​

构建日志堆栈 ​

日志级别 ​

写入日志消息 ​

上下文信息 ​

写入特定通道 ​

按需通道 ​

Monolog 通道自定义 ​

为通道自定义 Monolog ​

创建 Monolog 处理程序通道 ​

Monolog 格式化器 ​

Monolog 处理器 ​

通过工厂创建自定义通道 ​

使用 Pail 尾随日志消息 ​

安装 ​

用法 ​

过滤日志 ​

--filter ​

--message ​

--level ​

--user ​

日志记录

介绍

配置

可用的通道驱动

配置通道名称

通道先决条件

配置单通道和每日通道

配置 Papertrail 通道

配置 Slack 通道

日志记录弃用警告

构建日志堆栈

日志级别

写入日志消息

上下文信息

写入特定通道

按需通道

Monolog 通道自定义

为通道自定义 Monolog

创建 Monolog 处理程序通道

Monolog 格式化器

Monolog 处理器

通过工厂创建自定义通道

使用 Pail 尾随日志消息

安装

用法

过滤日志

`--filter`

`--message`

`--level`

`--user`