日志记录

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

介绍

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

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

在底层，Laravel 使用 Monolog 库，该库提供对各种强大日志处理器的支持。Laravel 使配置这些处理器变得轻而易举，允许您混合和匹配它们以自定义应用程序的日志处理。

配置

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

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

配置通道名称

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

php

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

可用的通道驱动

每个日志通道由一个“驱动”提供支持。驱动决定日志消息的实际记录方式和位置。每个 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 驱动的信息。

通道前提条件

配置单一和每日通道

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

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

此外，可以通过 days 选项配置 daily 通道的保留策略：

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

配置 Papertrail 通道

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

配置 Slack 通道

slack 通道需要一个 url 配置选项。此 URL 应与您为 Slack 团队配置的传入 webhook 的 URL 匹配。

默认情况下，Slack 只会接收 critical 级别及以上的日志；但是，您可以通过修改 Slack 日志通道配置数组中的 level 配置选项在 config/logging.php 配置文件中调整此设置。

记录弃用警告

PHP、Laravel 和其他库经常通知用户某些功能已被弃用，并将在未来版本中删除。如果您希望记录这些弃用警告，可以在应用程序的 config/logging.php 配置文件中指定首选的 deprecations 日志通道：

php

'deprecations' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),

'channels' => [
    ...
]

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

php

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

构建日志堆栈

如前所述，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。因此，在记录消息时，这两个通道都将有机会记录消息。然而，正如我们将在下面看到的，是否这些通道实际记录消息可能取决于消息的严重性/“级别”。

日志级别

注意上面示例中 syslog 和 slack 通道配置中存在的 level 配置选项。此选项确定消息必须达到的最低“级别”才能被通道记录。为 Laravel 的日志记录服务提供支持的 Monolog 提供了 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 facade 将信息写入日志。如前所述，记录器提供了 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 facade 的 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 facade 上的 channel 方法来检索并记录到配置文件中定义的任何通道：

php

use Illuminate\Support\Facades\Log;

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

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

php

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

按需通道

还可以通过在运行时提供配置来创建按需通道，而无需在应用程序的 logging 配置文件中存在该配置。为此，您可以将配置数组传递给 Log facade 的 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 实例创建后自定义（或“tap”）它。没有这些类应放置的常规位置，因此您可以在应用程序中创建一个目录来包含这些类：

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;

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 并未为每个处理器都包含内置通道。在某些情况下，您可能希望创建一个自定义通道，该通道仅仅是一个没有相应 Laravel 日志驱动的特定 Monolog 处理器的实例。这些通道可以使用 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`