日志

未匹配的标注
本文档最新版为 11.x,旧版本可能放弃维护,推荐阅读最新版!

日志

简介

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

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

在底层,Laravel 使用了 Monolog 库,它提供了多种强大的日志处理器。Laravel 使得配置这些处理器非常简单,你可以自由组合它们,从而自定义应用程序的日志处理方式。

配置

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

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

可用通道驱动

每个日志通道都由一个“驱动(driver)”提供支持。驱动决定日志消息实际如何以及记录到哪里。每个 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 驱动。

[!注意]
查看高级通道自定义文档,以了解更多关于 monologcustom 驱动的信息。

配置通道名称

默认情况下,Monolog 会使用与当前环境匹配的“通道名称”实例化,例如 productionlocal。要更改此值,可以在通道配置中添加 name 选项:

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

通道前置条件

配置 Single 和 Daily 通道

singledaily 通道有三个可选的配置项:bubblepermissionlocking

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

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

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

配置 Papertrail 通道

papertrail 通道需要 hostport 配置项。可以通过环境变量 PAPERTRAIL_URLPAPERTRAIL_PORT 设置这些值。相关值可以从 Papertrail 官方文档 获取。

配置 Slack 通道

slack 通道需要一个 url 配置项。可以通过环境变量 LOG_SLACK_WEBHOOK_URL 设置该 URL。这个 URL 应该对应你为 Slack 团队配置的 Incoming Webhook

默认情况下,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! add]
        '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 选项聚合了另外两个通道:syslogslack。因此,在记录消息时,这两个通道都有机会记录消息。然而,正如我们将在下文中看到的,这些通道是否实际记录消息可能取决于消息的严重性 /“级别”。

日志级别

请注意上面示例中 syslogslack 渠道配置里的 level 配置项。这个选项决定了一条消息在被该渠道记录之前必须达到的最小“级别”。Laravel 的日志服务由 Monolog 驱动,它提供了 RFC 5424 规范 中定义的所有日志级别。按严重性递减顺序排列,这些日志级别分别是:emergencyalertcriticalerrorwarningnoticeinfodebug

例如,我们使用 debug 方法记录一条消息:

Log::debug('An informational message.');

根据配置,syslog 渠道会将该消息写入系统日志;但是,由于这条消息的级别不是 critical 或更高,所以不会被发送到 Slack。不过,如果我们记录一条 emergency 消息,它会同时被写入系统日志并发送到 Slack,因为 emergency 级别高于两个渠道的最小级别阈值:

Log::emergency('The system is down!');

写入日志消息

你可以使用 Log 门面 将信息写入日志。如前所述,日志器提供了 RFC 5424 规范 中定义的八个日志级别:emergencyalertcriticalerrorwarningnoticeinfodebug

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 实例创建之后对其进行自定义(或“tap”进入)。这些类没有约定的存放位置,因此你可以在应用中自由创建一个目录来存放这些类:

'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
{
    /**
     * 自定义给定的 logger 实例。
     */
    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 拥有多种可用的处理器(handlers),而 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 将作为默认格式化器使用。
但是,你可以通过 formatterformatter_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],
        ],
    ],
],

通过工厂创建自定义渠道(Creating Custom Channels via Factories)

如果你希望定义一个完全自定义的渠道,并且能够完全控制 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 实时追踪日志消息(Tailing Log Messages Using Pail)

在调试问题或监控应用的特定错误类型时,你通常需要实时追踪应用程序的日志。

Laravel Pail 是一个软件包,它允许你直接从命令行轻松查看 Laravel 应用的日志文件。
与标准的 tail 命令不同,Pail 被设计为可与任意日志驱动一起工作,包括 Sentry 或 Flare。
此外,Pail 还提供了一系列有用的过滤器,帮助你快速找到所需的日志信息。

pail-example.png

安装

[!警告]
Laravel Pail 需要 PHP 8.2+PCNTL 扩展。

要开始使用,可以通过 Composer 包管理器将 Pail 安装到你的项目中:

composer require laravel/pail

使用 (Usage)

要开始追踪日志,运行 pail 命令:

php artisan pail

如果想增加输出的详细程度并避免截断 (),可以使用 -v 选项:

php artisan pail -v

如果需要最大化详细程度,并显示异常堆栈跟踪,可以使用 -vv 选项:

php artisan pail -vv

要停止追踪日志,可以随时按下 Ctrl+C

过滤日志 (Filtering Logs)

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

本文章首发在 LearnKu.com 网站上。

本译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。

原文地址:https://learnku.com/docs/laravel/12.x/lo...

译文地址:https://learnku.com/docs/laravel/12.x/lo...

上一篇 下一篇
《L04 微信小程序从零到发布》
从小程序个人账户申请开始,带你一步步进行开发一个微信小程序,直到提交微信控制台上线发布。
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
贡献者:2
讨论数量: 0
发起讨论 只看当前版本


暂无话题~