日志
简介
为帮助你了解应用程序中发生的情况，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 驱动程序。 |
[!NOTE]
查阅 高级通道自定义 文档，了解有关monolog和custom驱动的更多信息。
配置通道名称
默认情况下，Monolog 会使用与当前环境匹配的“通道名称”进行实例化，例如 production 或 local。要更改此值，你可以在通道配置中添加 name 选项：
php
'stack' => [
'driver' => 'stack',
'name' => 'channel-name',
'channels' => ['single', 'slack'],
],通道前置要求
配置 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 日志通道：
php
'deprecations' => [
'channel' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
'trace' => env('LOG_DEPRECATIONS_TRACE', false),
],
'channels' => [
// ...
]或者，你可以定义一个名为 deprecations 的日志通道。如果存在一个同名的日志通道，它将始终用于记录废弃：
php
'channels' => [
'deprecations' => [
'driver' => 'single',
'path' => storage_path('logs/php-deprecation-warnings.log'),
],
],构建日志堆栈
如前所述，stack 驱动程序允许你将多个通道组合成一个日志通道，以方便使用。为了说明如何使用日志堆栈，我们来看一个你在生产应用程序中可能会看到的配置示例：
php
'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 选项聚合了另外两个通道：syslog 和 slack。因此，在记录消息时，这两个通道都有机会记录该消息。然而，正如我们将在下面看到的，这些通道是否实际记录消息可能由消息的严重程度 / “级别”决定。
日志级别
请注意上述示例中 syslog 和 slack 通道配置上的 level 配置选项。此选项决定了消息必须达到的最低“级别”才能被通道记录。为 Laravel 日志服务提供支持的 Monolog，提供了 RFC 5424 规范中定义的所有日志级别。按严重程度降序排列，这些日志级别是：emergency（紧急）、alert（警报）、critical（关键）、error（错误）、warning（警告）、notice（通知）、info（信息）和 debug（调试）。
那么，假设我们使用 debug 方法记录一条消息：
php
Log::debug('An informational message.');鉴于我们的配置，syslog 通道会将消息写入系统日志；但是，由于该错误消息未达到 critical 或更高，因此不会发送到 Slack。但是，如果我们记录一条 emergency 消息，它将被发送到系统日志和 Slack，因为 emergency 级别高于我们为这两个通道设置的最低级别阈值：
php
Log::emergency('The system is down!');写入日志消息
你可以使用 Log 门面 将信息写入日志。如前所述，日志记录器提供了 RFC 5424 规范中定义的八个日志级别：emergency（紧急）、alert（警报）、critical（关键）、error（错误）、warning（警告）、notice（通知）、info（信息）和 debug（调试）：
php
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
<?php
namespace App\Http\Controllers;
use App\Models\User;
use Illuminate\Support\Facades\Log;
use Illuminate\View\View;
class UserController extends Controller
{
/**
* Show the profile for the given user.
*/
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)
]);
}
}上下文信息
可以将上下文数据数组传递给日志方法。这些上下文数据将与日志消息一起格式化并显示：
php
use Illuminate\Support\Facades\Log;
Log::info('User {id} failed to login.', ['id' => $user->id]);有时，你可能希望指定一些上下文信息，这些信息应包含在特定通道的所有后续日志条目中。例如，你可能希望记录与应用程序的每个传入请求关联的请求 ID。为此，你可以调用 Log 门面的 withContext 方法：
php
<?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
<?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
]);
// ...
}
}[!NOTE]
如果你需要在处理队列任务时共享日志上下文，可以使用任务中间件。
写入特定通道
有时，你可能希望将消息记录到应用程序默认通道之外的通道。你可以使用 Log 门面上的 channel 方法来获取并记录到配置文件中定义的任何通道：
php
use Illuminate\Support\Facades\Log;
Log::channel('slack')->info('Something happened!');如果你想创建一个由多个通道组成的按需日志堆栈，可以使用 stack 方法：
php
Log::stack(['single', 'slack'])->info('Something happened!');按需通道
还可以通过在运行时提供配置来创建按需通道，而无需将该配置包含在应用程序的 logging 配置文件中。为此，你可以将配置数组传递给 Log 门面的 build 方法：
php
use Illuminate\Support\Facades\Log;
Log::build([
'driver' => 'single',
'path' => storage_path('logs/custom.log'),
])->info('Something happened!');你可能还希望在按需日志堆栈中包含一个按需通道。这可以通过将你的按需通道实例包含在传递给 stack 方法的数组中来实现：
php
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 实例创建后对其进行自定义（或“接入”）。这些类没有约定俗成的放置位置，因此你可以自由地在应用程序中创建目录来存放这些类：
php
'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
<?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%'
));
}
}
}[!NOTE]
你所有的“接入”类都由服务容器解析，因此它们所需的任何构造函数依赖都将自动注入。
创建 Monolog 处理器通道
Monolog 有各种可用的处理器，但 Laravel 并未为每个处理器都包含一个内置通道。在某些情况下，你可能希望创建一个自定义通道，它仅仅是某个特定 Monolog 处理器的一个实例，而该处理器没有对应的 Laravel 日志驱动。可以使用 monolog 驱动轻松创建这些通道。
使用 monolog 驱动时，handler 配置选项用于指定将实例化哪个处理器。此外，处理器所需的任何构造函数参数可以使用 handler_with 配置选项指定：
php
'logentries' => [
'driver' => 'monolog',
'handler' => Monolog\Handler\SyslogUdpHandler::class,
'handler_with' => [
'host' => 'my.logentries.internal.datahubhost.company.com',
'port' => '10000',
],
],Monolog 格式化程序
使用 monolog 驱动时，Monolog LineFormatter 将用作默认格式化程序。但是，你可以使用 formatter 和 formatter_with 配置选项来自定义传递给处理器的格式化程序类型：
php
'browser' => [
'driver' => 'monolog',
'handler' => Monolog\Handler\BrowserConsoleHandler::class,
'formatter' => Monolog\Formatter\HtmlFormatter::class,
'formatter_with' => [
'dateFormat' => 'Y-m-d',
],
],如果你使用的 Monolog 处理器能够提供自己的格式化程序，可以将 formatter 配置选项的值设置为 default：
php
'newrelic' => [
'driver' => 'monolog',
'handler' => Monolog\Handler\NewRelicHandler::class,
'formatter' => 'default',
],Monolog 处理器
Monolog 也可以在记录消息之前处理它们。你可以创建自己的处理器，或使用 Monolog 提供的现有处理器。
如果你想为 monolog 驱动自定义处理器，请将 processors 配置值添加到通道的配置中：
php
'memory' => [
'driver' => 'monolog',
'handler' => Monolog\Handler\StreamHandler::class,
'handler_with' => [
'stream' => 'php://stderr',
],
'processors' => [
// Simple syntax...
Monolog\Processor\MemoryUsageProcessor::class,
// With options...
[
'processor' => Monolog\Processor\PsrLogMessageProcessor::class,
'with' => ['removeUsedContextFields' => true],
],
],
],通过工厂创建自定义通道
如果你想定义一个完全自定义的通道，并在其中完全控制 Monolog 的实例化和配置，你可以在 config/logging.php 配置文件中指定 custom 驱动类型。你的配置应包含一个 via 选项，其中包含将调用以创建 Monolog 实例的工厂类的名称：
php
'channels' => [
'example-custom-channel' => [
'driver' => 'custom',
'via' => App\Logging\CreateCustomLogger::class,
],
],配置 custom 驱动通道后，你就可以定义将创建 Monolog 实例的类了。此类只需要一个 __invoke 方法，该方法应返回 Monolog 日志记录器实例。该方法将接收通道配置数组作为其唯一参数：
php
<?php
namespace App\Logging;
use Monolog\Logger;
class CreateCustomLogger
{
/**
* Create a custom Monolog instance.
*/
public function __invoke(array $config): Logger
{
return new Logger(/* ... */);
}
}使用 Pail 跟踪日志消息
通常，你可能需要实时跟踪应用程序的日志。例如，在调试问题时或在监视应用程序日志以查找特定类型的错误时。
Laravel Pail 是一个软件包，允许你直接从命令行轻松深入 Laravel 应用程序的日志文件。与标准 tail 命令不同，Pail 旨在与任何日志驱动程序配合使用，包括 Sentry 或 Flare。此外，Pail 提供了一组有用的过滤器，可帮助你快速找到所需内容。
安装
[!WARNING]
Laravel Pail 需要 PCNTL PHP 扩展。
首先，使用 Composer 包管理器将 Pail 安装到你的项目中：
bash
composer require --dev laravel/pail用法
要开始跟踪日志，请运行 pail 命令：
bash
php artisan pail要增加输出的详细程度并避免截断（…），请使用 -v 选项：
bash
php artisan pail -v对于最大详细程度并显示异常堆栈跟踪，请使用 -vv 选项：
bash
php artisan pail -vv要停止跟踪日志，请随时按 Ctrl+C。
筛选日志
--filter
你可以使用 --filter 选项按日志类型、文件、消息和堆栈跟踪内容筛选日志：
bash
php artisan pail --filter="QueryException"--message
要仅按消息筛选日志，可以使用 --message 选项：
bash
php artisan pail --message="User created"--level
--level 选项可用于按日志的日志级别筛选日志：
bash
php artisan pail --level=error--user
若要仅显示给定用户通过身份验证时写入的日志，你可以将用户 ID 提供给 --user 选项：
bash
php artisan pail --user=1