日志

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

简介

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

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

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

配置

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

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

可用的通道驱动

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

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

NOTE

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

配置通道名称

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

php

'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`	应保留的每日日志文件的天数。	`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 配置选项。此选项决定了消息必须达到的最低“级别”才能被通道记录。驱动 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 门面将信息写入日志。如前所述，日志记录器提供了 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\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 配置选项用于指定将实例化哪个处理程序。可选地，处理程序需要的任何构造函数参数可以使用 handler_with 配置选项指定：

php

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

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

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 需要 PCNTL PHP 扩展。

首先，使用 Composer 包管理器将 Pail 安装到你的项目中：

shell

composer require --dev laravel/pail

使用方法

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

shell

php artisan pail

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

shell

php artisan pail -v

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

shell

php artisan pail -vv

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

过滤日志

`--filter`

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

shell

php artisan pail --filter="QueryException"

`--message`

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

shell

php artisan pail --message="User created"

`--level`

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

shell

php artisan pail --level=error

`--user`

要仅显示在给定用户通过身份验证时写入的日志，你可以向 --user 选项提供用户的 ID：

shell

php artisan pail --user=1

日志 ​

简介 ​

配置 ​

可用的通道驱动 ​

配置通道名称 ​

通道前提条件 ​

配置 Single 和 Daily 通道 ​

配置 Papertrail 通道 ​

配置 Slack 通道 ​

记录弃用警告 ​

构建日志堆栈 ​

日志级别 ​

写入日志消息 ​

上下文信息 ​

写入特定通道 ​

按需通道 ​

Monolog 通道自定义 ​

为通道自定义 Monolog ​

创建 Monolog 处理程序通道 ​

Monolog 格式化器 ​

Monolog 处理器 ​

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

使用 Pail 跟踪日志消息 ​

安装 ​

使用方法 ​

过滤日志 ​

--filter ​

--message ​

--level ​

--user ​

日志

简介

配置

可用的通道驱动

配置通道名称

通道前提条件

配置 Single 和 Daily 通道

配置 Papertrail 通道

配置 Slack 通道

记录弃用警告

构建日志堆栈

日志级别

写入日志消息

上下文信息

写入特定通道

按需通道

Monolog 通道自定义

为通道自定义 Monolog

创建 Monolog 处理程序通道

Monolog 格式化器

Monolog 处理器

通过工厂创建自定义通道

使用 Pail 跟踪日志消息

安装

使用方法

过滤日志

`--filter`

`--message`

`--level`

`--user`