日志
引言
为了帮助您更好地了解应用程序中的发生情况，Laravel 提供了强大的日志服务，允许您将日志消息写入文件、系统错误日志，甚至通过 Slack 通知整个团队。
Laravel 的日志基于 “通道”。每个通道代表一种特定的写入日志信息的方式。例如，single 通道将日志消息写入单一的日志文件，而 slack 通道则将日志消息发送到 Slack。根据消息的严重性，日志消息可以被写入多个通道。
在幕后，Laravel 使用了 Monolog 库，它支持多种强大的日志处理程序。Laravel 使得配置这些处理程序变得简单，您可以自由组合和匹配它们，以定制您的应用程序的日志处理方式。
配置
控制应用程序日志行为的所有配置选项都集中在 config/logging.php 配置文件中。该文件允许您配置应用程序的日志通道，因此请务必查看每个可用通道及其选项。以下是一些常见选项的概述。
默认情况下，Laravel 在记录消息时会使用 stack 通道。stack 通道用于将多个日志通道聚合为一个通道。有关如何构建日志堆栈的更多信息，请参阅下面的文档。
可用的通道驱动
每个日志通道都有一个 “驱动程序”。驱动程序决定了日志消息的记录方式和位置。以下是每个 Laravel 应用程序中可用的日志通道驱动程序。大多数驱动程序的条目已经存在于您的应用程序的 config/logging.php 配置文件中，因此请务必查看该文件，以熟悉其内容：
| 名称 | 描述 |
|---|---|
custom |
一个调用指定工厂以创建通道的驱动程序。 |
daily |
基于 |
errorlog |
基于 |
monolog |
一个 Monolog 工厂驱动程序，可以使用任何支持的 Monolog 处理程序。 |
papertrail |
基于 |
single |
基于单一文件或路径的日志通道（ |
slack |
基于 |
stack |
一个包装器，用于创建 “多通道” 通道。 |
syslog |
基于 |
|
查看关于【高级通道自定义】的文档，以了解更多关于 |
通道前提条件
配置单一通道和每日通道
single 通道和 daily 通道有三个可选的配置选项：bubble、permission 和 locking。
| 名称 | 描述 | 默认值 |
|---|---|---|
|
指示消息在处理后是否应向其它通道传递。 |
|
|
尝试在写入日志之前锁定日志文件。 |
|
|
日志文件的权限。 |
|
此外，daily 通道的保留策略可以通过 LOG_DAILY_DAYS 环境变量或设置 days 配置选项来配置。
| 名称 | 描述 | 默认值 |
|---|---|---|
|
每日日志文件应保留的天数。 |
|
配置 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' => [
'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'],
'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 提供支持，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 【facade】 向日志中写入信息。如前所述，日志提供了 【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('正在显示用户 {id} 的个人资料', ['id' => $id]);
return view('user.profile', [
'user' => User::findOrFail($id)
]);
}
}上下文信息
可以将一组上下文数据传递给日志方法。这些上下文数据将在日志消息中进行格式化并显示：
use Illuminate\Support\Facades\Log;
Log::info('用户 {id} 登录失败。', ['id' => $user->id]);有时，您可能希望指定一些上下文信息，这些信息应包含在特定通道的所有后续日志条目中。例如，您可能希望记录与每个传入请求关联的请求 ID。为此，您可以调用 Log facade 的 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 facade 的 channel 方法来检索并记录到配置文件中定义的任何通道：
use Illuminate\Support\Facades\Log;
Log::channel('slack')->info('发生了一些事情！');如果您希望创建一个按需的日志堆栈，包含多个通道，您可以使用 stack 方法：
Log::stack(['single', 'slack'])->info('发生了一些事情！');按需通道
您还可以通过在运行时提供配置来创建按需通道，而不需要该配置存在于应用程序的 logging 配置文件中。为此，您可以将配置数组传递给 Log facade 的 build 方法：
use Illuminate\Support\Facades\Log;
Log::build([
'driver' => 'single',
'path' => storage_path('logs/custom.log'),
])->info('发生了一些事情！');您还可以将按需通道包含在按需日志堆栈中。可以通过将您的按需通道实例包含在传递给 stack 方法的数组中来实现：
use Illuminate\Support\Facades\Log;
$channel = Log::build([
'driver' => 'single',
'path' => storage_path('logs/custom.log'),
]);
Log::stack(['slack', $channel])->info('发生了一些事情！');Monolog 通道自定义
自定义 Monolog 通道
有时你可能需要完全控制如何为现有频道配置 Monolog。例如，你可能想为 Laravel 内置的 single 频道配置一个自定义的 Monolog FormatterInterface 实现。
要开始，首先在频道的配置中定义一个 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
{
/**
* Customize the given logger instance.
*/
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 提供了各种【可用的处理器】，而 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 会被用作默认格式化器。不过，您可以通过 formatter 和 formatter_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 配置文件中指定一个自定义的驱动类型。您的配置应包括一个 via 选项，其中包含用于创建 Monolog 实例的工厂类名称：
'channels' => [
'example-custom-channel' => [
'driver' => 'custom',
'via' => App\Logging\CreateCustomLogger::class,
],
],一旦配置了自定义驱动通道，您就可以定义一个类来创建 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 命令：
php artisan pail为了提高输出的详细程度并避免截断（…），可以使用 -v 选项：
php artisan pail -v要获得最大详细度并显示异常堆栈跟踪，请使用 -vv 选项：
php artisan pail -vv要停止查看日志，随时按 Ctrl+C。