日志

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

日志记录

介绍

为了帮助您更好地了解应用程序内部发生的情况,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 驱动程序 |

提醒:查看高级通道定制文档以了解有关 monologcustom 驱动程序的更多信息。

配置通道名称

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

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

通道先决条件

配置单通道和日志通道

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

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

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

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

配置 Papertrail 通道

papertrail 通道需要 hostport 配置选项。这些可以通过 PAPERTRAIL_URLPAPERTRAIL_PORT 环境变量定义。您可以在 Papertrail 获取这些值。

配置 Slack 通道

slack 通道需要一个 url 配置选项。此值可以通过 LOG_SLACK_WEBHOOK_URL 环境变量定义。此 URL 应与您为 Slack 团队配置的 入站 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 规范中定义的所有日志级别。按严重程度降序排列的,这些日志级别是: emergency(紧急), alert(警告), critical(关键), error(错误), warning(警告), notice(通知), info(信息), 和 debug(调试)

因此,假设我们使用 debug 方法记录一条消息:

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

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

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

写入日志消息

你可以使用 Log 门面 将信息写入日志。如前所述,记录器提供了 RFC 5424 规范 中定义的八个日志级别: emergency(紧急), alert(警告), critical(关键), error(错误), warning(警告), notice(通知), info(信息), 和 debug(调试):

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('Showing the user profile for user: {id}', ['id' => $id]);

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

日志级别

请注意上面示例中 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 facade 向日志写入信息。正如之前提到的,日志记录器提供了 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\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)
        ]);
    }
}

上下文信息

可以向日志方法传递一组上下文数据。这些上下文数据将与日志消息一起格式化和显示:

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
{
    /**
     * Handle an incoming request.
     *
     * @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
{
    /**
     * Handle an incoming request.
     *
     * @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
        ]);

        // ...
    }
}

[注意]
如果在处理排队作业时需要共享日志上下文,可以使用 job middleware.

上下文信息

可以向日志方法传递一组上下文数据。这些上下文数据将与日志消息一起格式化和显示:

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

        // ...
    }
}

注意
如果您需要在处理队列任务时共享日志上下文,可以使用 job middleware.

写入指定通道

有时,你可能希望将消息记录到应用程序默认通道以外的通道。你可以使用 Log facade 的 channel 方法来检索并记录配置文件中定义的任何通道:

use Illuminate\Support\Facades\Log;

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

如果你想创建一个由多个通道组成的按需记录堆栈,可以使用 stack 方法:

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

按需通道

还可以创建一个按需通道,方法是在运行时提供配置,而无需将该配置包含在应用程序的 logging 配置文件中。为此,可以将配置数组传递给 Log facade 的 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 实例后应有机会自定义(或 「tab」)它。没有这些类应放置在何处的惯例位置,因此您可以在应用程序中创建一个目录以包含这些类:

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

注意
所有的 「tab」类都由 服务容器 解析,因此它们所需的任何构造函数依赖关系都将自动注入。

创建 Monolog 处理程序通道

Monolog 有多种 可用的处理程序,而 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 将用作默认格式化程序。但是,你可以使用 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 处理器

Monolog 也可以在记录消息之前对其进行处理。你可以创建你自己的处理器或使用 Monolog 提供的现有处理器

如果你想为 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 提供了一组有用的过滤器,帮助你找到所需的内容。

pail-example.png

安装

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

首先,请使用 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

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

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

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

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

上一篇 下一篇
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
《G01 Go 实战入门》
从零开始带你一步步开发一个 Go 博客项目,让你在最短的时间内学会使用 Go 进行编码。项目结构很大程度上参考了 Laravel。
贡献者:10
讨论数量: 0
发起讨论 只看当前版本


暂无话题~