跳转至内容

日志

简介

为了帮助您深入了解应用程序内部发生的情况,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 选项。

1'stack' => [
2 'driver' => 'stack',
3 'name' => 'channel-name',
4 'channels' => ['single', 'slack'],
5],

通道前提条件

配置 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 应与您为 Slack 团队配置的传入 Webhook URL 相匹配。

默认情况下,Slack 仅接收 critical 级别及以上的日志;但是,您可以使用 LOG_LEVEL 环境变量或修改 Slack 日志通道配置数组中的 level 配置选项来进行调整。

弃用警告日志记录

PHP、Laravel 以及其他库通常会通知用户其某些功能已被弃用,并将在未来版本中移除。如果您希望记录这些弃用警告,可以使用 LOG_DEPRECATIONS_CHANNEL 环境变量指定您偏好的 deprecations 日志通道,或者在应用程序的 config/logging.php 配置文件中进行设置。

1'deprecations' => [
2 'channel' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
3 'trace' => env('LOG_DEPRECATIONS_TRACE', false),
4],
5 
6'channels' => [
7 // ...
8]

或者,您可以定义一个名为 deprecations 的日志通道。如果存在以此命名的日志通道,它将始终被用于记录弃用信息。

1'channels' => [
2 'deprecations' => [
3 'driver' => 'single',
4 'path' => storage_path('logs/php-deprecation-warnings.log'),
5 ],
6],

构建日志堆栈

如前所述,stack 驱动程序允许您为了方便起见将多个通道合并为一个日志通道。为了说明如何使用日志堆栈,让我们看一个您在生产环境应用程序中可能会看到的配置示例。

1'channels' => [
2 'stack' => [
3 'driver' => 'stack',
4 'channels' => ['syslog', 'slack'],
5 'ignore_exceptions' => false,
6 ],
7 
8 'syslog' => [
9 'driver' => 'syslog',
10 'level' => env('LOG_LEVEL', 'debug'),
11 'facility' => env('LOG_SYSLOG_FACILITY', LOG_USER),
12 'replace_placeholders' => true,
13 ],
14 
15 'slack' => [
16 'driver' => 'slack',
17 'url' => env('LOG_SLACK_WEBHOOK_URL'),
18 'username' => env('LOG_SLACK_USERNAME', 'Laravel Log'),
19 'emoji' => env('LOG_SLACK_EMOJI', ':boom:'),
20 'level' => env('LOG_LEVEL', 'critical'),
21 'replace_placeholders' => true,
22 ],
23],

让我们分析一下这个配置。首先,注意我们的 stack 通道通过其 channels 选项聚合了另外两个通道:syslogslack。因此,在记录消息时,这两个通道都有机会记录该消息。然而,正如我们在下面将看到的,这些通道是否实际记录消息取决于消息的严重程度 /“级别”。

日志级别

请注意上述 syslogslack 通道配置中存在的 level 配置选项。此选项决定了消息被通道记录所需的最低“级别”。为 Laravel 日志服务提供支持的 Monolog,提供了 RFC 5424 规范中定义的所有日志级别。按严重程度降序排列,这些日志级别为:emergencyalertcriticalerrorwarningnoticeinfodebug

那么,假设我们使用 debug 方法记录了一条消息。

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

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

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

写入日志消息

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

1use Illuminate\Support\Facades\Log;
2 
3Log::emergency($message);
4Log::alert($message);
5Log::critical($message);
6Log::error($message);
7Log::warning($message);
8Log::notice($message);
9Log::info($message);
10Log::debug($message);

您可以调用这些方法中的任何一个来为相应的级别记录消息。默认情况下,消息将被写入由您的 logging 配置文件配置的默认日志通道。

1<?php
2 
3namespace App\Http\Controllers;
4 
5use App\Models\User;
6use Illuminate\Support\Facades\Log;
7use Illuminate\View\View;
8 
9class UserController extends Controller
10{
11 /**
12 * Show the profile for the given user.
13 */
14 public function show(string $id): View
15 {
16 Log::info('Showing the user profile for user: {id}', ['id' => $id]);
17 
18 return view('user.profile', [
19 'user' => User::findOrFail($id)
20 ]);
21 }
22}

上下文信息

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

1use Illuminate\Support\Facades\Log;
2 
3Log::info('User {id} failed to login.', ['id' => $user->id]);

有时,您可能希望指定一些应包含在特定通道中所有后续日志条目中的上下文信息。例如,您可能希望记录与应用程序的每个传入请求相关联的请求 ID。要实现这一点,您可以调用 Log 门面的 withContext 方法。

1<?php
2 
3namespace App\Http\Middleware;
4 
5use Closure;
6use Illuminate\Http\Request;
7use Illuminate\Support\Facades\Log;
8use Illuminate\Support\Str;
9use Symfony\Component\HttpFoundation\Response;
10 
11class AssignRequestId
12{
13 /**
14 * Handle an incoming request.
15 *
16 * @param \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response) $next
17 */
18 public function handle(Request $request, Closure $next): Response
19 {
20 $requestId = (string) Str::uuid();
21 
22 Log::withContext([
23 'request-id' => $requestId
24 ]);
25 
26 $response = $next($request);
27 
28 $response->headers->set('Request-Id', $requestId);
29 
30 return $response;
31 }
32}

如果您想在*所有*日志通道中共享上下文信息,可以调用 Log::shareContext() 方法。此方法会将上下文信息提供给所有已创建的通道以及随后创建的任何通道。

1<?php
2 
3namespace App\Http\Middleware;
4 
5use Closure;
6use Illuminate\Http\Request;
7use Illuminate\Support\Facades\Log;
8use Illuminate\Support\Str;
9use Symfony\Component\HttpFoundation\Response;
10 
11class AssignRequestId
12{
13 /**
14 * Handle an incoming request.
15 *
16 * @param \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response) $next
17 */
18 public function handle(Request $request, Closure $next): Response
19 {
20 $requestId = (string) Str::uuid();
21 
22 Log::shareContext([
23 'request-id' => $requestId
24 ]);
25 
26 // ...
27 }
28}

如果您需要在处理排队作业时共享日志上下文,可以使用 作业中间件

写入特定通道

有时您可能希望将消息记录到应用程序默认通道以外的其他通道。您可以使用 Log 门面上的 channel 方法来检索并在配置文件中定义的任何通道中进行记录。

1use Illuminate\Support\Facades\Log;
2 
3Log::channel('slack')->info('Something happened!');

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

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

按需通道

也可以通过在运行时提供配置来创建按需通道,而无需将该配置存放在应用程序的 logging 配置文件中。要实现这一点,您可以将配置数组传递给 Log 门面的 build 方法。

1use Illuminate\Support\Facades\Log;
2 
3Log::build([
4 'driver' => 'single',
5 'path' => storage_path('logs/custom.log'),
6])->info('Something happened!');

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

1use Illuminate\Support\Facades\Log;
2 
3$channel = Log::build([
4 'driver' => 'single',
5 'path' => storage_path('logs/custom.log'),
6]);
7 
8Log::stack(['slack', $channel])->info('Something happened!');

Monolog 通道自定义

为通道自定义 Monolog

有时您可能需要完全控制 Monolog 如何为现有通道进行配置。例如,您可能想为 Laravel 内置的 single 通道配置自定义的 Monolog FormatterInterface 实现。

首先,在通道的配置中定义一个 tap 数组。tap 数组应包含一个类列表,这些类有机会在 Monolog 实例创建后对其进行自定义(或“接入”)。这些类没有特定的存放位置,因此您可以自由地在应用程序中创建一个目录来存放它们。

1'single' => [
2 'driver' => 'single',
3 'tap' => [App\Logging\CustomizeFormatter::class],
4 'path' => storage_path('logs/laravel.log'),
5 'level' => env('LOG_LEVEL', 'debug'),
6 'replace_placeholders' => true,
7],

配置完通道的 tap 选项后,就可以定义将自定义 Monolog 实例的类了。此类只需要一个方法:__invoke,它接收一个 Illuminate\Log\Logger 实例。Illuminate\Log\Logger 实例会将所有方法调用代理给底层的 Monolog 实例。

1<?php
2 
3namespace App\Logging;
4 
5use Illuminate\Log\Logger;
6use Monolog\Formatter\LineFormatter;
7 
8class CustomizeFormatter
9{
10 /**
11 * Customize the given logger instance.
12 */
13 public function __invoke(Logger $logger): void
14 {
15 foreach ($logger->getHandlers() as $handler) {
16 $handler->setFormatter(new LineFormatter(
17 '[%datetime%] %channel%.%level_name%: %message% %context% %extra%'
18 ));
19 }
20 }
21}

所有的“tap”类都由 服务容器 解析,因此它们所需的任何构造函数依赖项都将被自动注入。

创建 Monolog 处理程序通道

Monolog 拥有多种可用的处理程序,而 Laravel 并没有为每一个处理程序包含内置通道。在某些情况下,您可能希望创建一个仅作为特定 Monolog 处理程序实例的自定义通道,而该处理程序没有对应的 Laravel 日志驱动程序。这些通道可以使用 monolog 驱动程序轻松创建。

使用 monolog 驱动程序时,handler 配置选项用于指定将要实例化的处理程序。可选择地,可以使用 handler_with 配置选项指定处理程序所需的任何构造函数参数。

1'logentries' => [
2 'driver' => 'monolog',
3 'handler' => Monolog\Handler\SyslogUdpHandler::class,
4 'handler_with' => [
5 'host' => 'my.logentries.internal.datahubhost.company.com',
6 'port' => '10000',
7 ],
8],

Monolog 格式化程序

使用 monolog 驱动程序时,Monolog 的 LineFormatter 将作为默认格式化程序使用。但是,您可以使用 formatterformatter_with 配置选项自定义传递给处理程序的格式化程序类型。

1'browser' => [
2 'driver' => 'monolog',
3 'handler' => Monolog\Handler\BrowserConsoleHandler::class,
4 'formatter' => Monolog\Formatter\HtmlFormatter::class,
5 'formatter_with' => [
6 'dateFormat' => 'Y-m-d',
7 ],
8],

如果您使用的 Monolog 处理程序能够提供自己的格式化程序,则可以将 formatter 配置选项的值设置为 default

1'newrelic' => [
2 'driver' => 'monolog',
3 'handler' => Monolog\Handler\NewRelicHandler::class,
4 'formatter' => 'default',
5],

Monolog 处理器

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

如果您想为 monolog 驱动程序自定义处理器,请在通道的配置中添加 processors 配置值。

1'memory' => [
2 'driver' => 'monolog',
3 'handler' => Monolog\Handler\StreamHandler::class,
4 'handler_with' => [
5 'stream' => 'php://stderr',
6 ],
7 'processors' => [
8 // Simple syntax...
9 Monolog\Processor\MemoryUsageProcessor::class,
10 
11 // With options...
12 [
13 'processor' => Monolog\Processor\PsrLogMessageProcessor::class,
14 'with' => ['removeUsedContextFields' => true],
15 ],
16 ],
17],

通过工厂创建自定义通道

如果您想定义一个完全自定义的通道,并在此通道中对 Monolog 的实例化和配置拥有完全控制权,则可以在 config/logging.php 配置文件中指定 custom 驱动程序类型。您的配置应包含一个 via 选项,其中包含用于创建 Monolog 实例的工厂类的名称。

1'channels' => [
2 'example-custom-channel' => [
3 'driver' => 'custom',
4 'via' => App\Logging\CreateCustomLogger::class,
5 ],
6],

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

1<?php
2 
3namespace App\Logging;
4 
5use Monolog\Logger;
6 
7class CreateCustomLogger
8{
9 /**
10 * Create a custom Monolog instance.
11 */
12 public function __invoke(array $config): Logger
13 {
14 return new Logger(/* ... */);
15 }
16}

使用 Pail 跟踪日志消息

通常您可能需要实时跟踪应用程序的日志。例如,在调试问题或监控应用程序日志中特定类型的错误时。

Laravel Pail 是一个允许您直接从命令行轻松查看 Laravel 应用程序日志文件的包。与标准的 tail 命令不同,Pail 设计用于处理任何日志驱动程序,包括 Sentry 或 Flare。此外,Pail 还提供了一组有用的过滤器,帮助您快速找到所需内容。

安装

Laravel Pail 需要 PCNTL PHP 扩展。

首先,使用 Composer 包管理器将 Pail 安装到您的项目中:

1composer require --dev laravel/pail

用法

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

1php artisan pail

要增加输出的详细程度并避免截断 (…),请使用 -v 选项:

1php artisan pail -v

为了获得最大详细程度并显示异常堆栈跟踪,请使用 -vv 选项:

1php artisan pail -vv

要停止跟踪日志,请随时按下 Ctrl+C

过滤日志

--filter

您可以使用 --filter 选项按类型、文件、消息和堆栈跟踪内容过滤日志。

1php artisan pail --filter="QueryException"

--message

要仅按消息过滤日志,您可以使用 --message 选项。

1php artisan pail --message="User created"

--level

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

1php artisan pail --level=error

--user

要仅显示在特定用户身份验证期间写入的日志,您可以将用户的 ID 提供给 --user 选项。

1php artisan pail --user=1