日志记录 – 乌鸦嘴文档中心

介绍

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

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

在底层，Laravel 使用 Monolog (opens in a new tab) 库，该库为各种强大的日志处理程序提供支持。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 选项：

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

通道先决条件

配置 `single` 和 `daily` 通道

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

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

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

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

配置 `papertrail` 通道

papertrail 通道需要 host 和 port 配置选项。这些可以通过 PAPERTRAIL_URL 和 PAPERTRAIL_PORT 环境变量进行定义。您可以从 Papertrail (opens in a new tab) 获得这些值。

配置 `slack` 通道

slack 通道需要一个 url 配置选项。此值可以通过 LOG_SLACK_WEBHOOK_URL 环境变量进行定义。此 URL 应与您为 Slack 团队配置的传入 Webhook (opens in a new tab) 的 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'], // [tl! 添加]
        '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 日志'),
        '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 规范 (opens in a new tab) 中定义的所有日志级别。按照严重性从高到低的顺序，这些日志级别是：紧急、警报、严重、错误、警告、通知、信息和调试。

因此，想象一下我们使用 debug 方法记录一条消息：

Log::debug('一条信息性消息。');

根据我们的配置，syslog 通道将把消息写入系统日志；然而，由于错误消息不是 critical 或更高级别，所以它不会被发送到 Slack。但是，如果我们记录一个 emergency 消息，它将被发送到系统日志和 Slack，因为 emergency 级别高于我们为两个通道设置的最低级别阈值：

Log::emergency('系统已关闭！');

编写日志消息

您可以使用 Log 外观将信息写入日志。如前所述，日志记录器提供了 RFC 5424 规范 (opens in a new tab) 中定义的八个日志级别：紧急、警报、严重、错误、警告、通知、信息和调试：

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\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('正在显示用户: {id} 的个人资料', ['id' => $id]);

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

上下文信息

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

use Illuminate\Support\Facades\Log;

Log::info('用户 {id} 登录失败。', ['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('发生了某事！');

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

Log::stack(['single', 'slack'])->info('发生了某事！');

按需通道

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

use Illuminate\Support\Facades\Log;

Log::build([
  'driver' => 'single',
  'path' => storage_path('logs/custom.log'),
])->info('发生了某事！');

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

use Illuminate\Support\Facades\Log;

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

Log::stack(['slack', $channel])->info('发生了某事！');

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

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

创建 Monolog 处理程序通道

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

Monolog 还可以在记录消息之前对其进行处理。您可以创建自己的处理器或使用Monolog 提供的现有处理器 (opens in a new tab)。

如果您想为monolog驱动程序自定义处理器，可以在通道的配置中添加一个processors配置值：

'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 实例的工厂类的名称：

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

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

<?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+ (opens in a new tab)和PCNTL (opens in a new tab)扩展。

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

composer require 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`

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

php artisan pail --user=1

错误处理 Artisan 控制台

介绍

配置