日志记录
简介
为了帮助您更多地了解应用程序内部发生的事情,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 驱动程序。 |
查看关于 高级通道自定义 的文档,以了解更多关于 monolog
和 custom
驱动程序的信息。
配置通道名称
默认情况下,Monolog 使用与当前环境匹配的“通道名称”实例化,例如 production
或 local
。要更改此值,您可以将 name
选项添加到通道的配置中
1'stack' => [2 'driver' => 'stack',3 'name' => 'channel-name',4 'channels' => ['single', 'slack'],5],
通道先决条件
配置 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
日志通道
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
选项聚合了另外两个通道:syslog
和 slack
。因此,在记录消息时,这两个通道都有机会记录该消息。但是,正如我们将在下面看到的那样,这些通道是否实际记录消息可能取决于消息的严重程度/“级别”。
日志级别
请注意上面示例中 syslog
和 slack
通道配置中存在的 level
配置选项。此选项确定消息要被通道记录所需的最低“级别”。Monolog 为 Laravel 的日志记录服务提供支持,它提供了 RFC 5424 规范 中定义的所有日志级别。按严重程度降序排列,这些日志级别是:emergency、alert、critical、error、warning、notice、info 和 debug。
因此,假设我们使用 debug
方法记录一条消息
1Log::debug('An informational message.');
根据我们的配置,syslog
通道会将消息写入系统日志;但是,由于错误消息不是 critical
或更高级别,因此它不会发送到 Slack。但是,如果我们记录 emergency
消息,它将同时发送到系统日志和 Slack,因为 emergency
级别高于我们两个通道的最低级别阈值
1Log::emergency('The system is down!');
写入日志消息
您可以使用 Log
外观模式 将信息写入日志。如前所述,记录器提供了 RFC 5424 规范 中定义的八个日志级别:emergency、alert、critical、error、warning、notice、info 和 debug
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\Http\Controllers\Controller; 6use App\Models\User; 7use Illuminate\Support\Facades\Log; 8use Illuminate\View\View; 9 10class UserController extends Controller11{12 /**13 * Show the profile for the given user.14 */15 public function show(string $id): View16 {17 Log::info('Showing the user profile for user: {id}', ['id' => $id]);18 19 return view('user.profile', [20 'user' => User::findOrFail($id)21 ]);22 }23}
上下文信息
可以将上下文数据数组传递给日志方法。此上下文数据将被格式化并与日志消息一起显示
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 AssignRequestId12{13 /**14 * Handle an incoming request.15 *16 * @param \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response) $next17 */18 public function handle(Request $request, Closure $next): Response19 {20 $requestId = (string) Str::uuid();21 22 Log::withContext([23 'request-id' => $requestId24 ]);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 AssignRequestId12{13 /**14 * Handle an incoming request.15 *16 * @param \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response) $next17 */18 public function handle(Request $request, Closure $next): Response19 {20 $requestId = (string) Str::uuid();21 22 Log::shareContext([23 'request-id' => $requestId24 ]);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 实例创建后自定义(或“tap into”)它。没有约定俗成的位置来放置这些类,因此您可以自由地在应用程序中创建一个目录来包含这些类
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): void14 {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
配置选项用于指定将要实例化的处理程序。可选地,可以使用 with
配置选项指定处理程序需要的任何构造函数参数
1'logentries' => [2 'driver' => 'monolog',3 'handler' => Monolog\Handler\SyslogUdpHandler::class,4 'with' => [5 'host' => 'my.logentries.internal.datahubhost.company.com',6 'port' => '10000',7 ],8],
Monolog 格式化器
当使用 monolog
驱动程序时,Monolog LineFormatter
将用作默认格式化器。但是,您可以使用 formatter
和 formatter_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 '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): Logger13 {14 return new Logger(/* ... */);15 }16}
使用 Pail 追踪日志消息
通常,您可能需要实时追踪应用程序的日志。例如,在调试问题或监视应用程序日志中特定类型的错误时。
Laravel Pail 是一个软件包,允许您直接从命令行轻松深入了解 Laravel 应用程序的日志文件。与标准的 tail
命令不同,Pail 旨在与任何日志驱动程序一起使用,包括 Sentry 或 Flare。此外,Pail 提供了一组有用的过滤器,以帮助您快速找到您正在寻找的内容。

安装
要开始使用,请使用 Composer 包管理器将 Pail 安装到您的项目中
1composer require 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