Logging 11个月前

介绍

为了帮助您更多地了解应用程序中发生的事情，Laravel 提供了强大的日志记录服务，允许您将日志记录到文件、系统错误日志，甚至记录到 Slack 以通知您的整个团队。

Laravel 日志基于「 通道 」。 每个通道代表一种写入日志信息的特定方式。 例如，single 通道是将日志写入到单个日志文件中。而 slack 通道是将日志发送到 Slack 上。 基于它们的重要程度，日志可以被写入到多个通道中去。

在底层，Laravel 利用 Monolog 库，它为各种强大的日志处理程序提供了支持。 Laravel 使配置这些处理程序变得轻而易举，允许您混合和匹配它们，以自定义应用程序的方式完成日志处理。

配置

所有应用程序的日志行为配置选项都位于 config/logging.php 配置文件中。 该文件允许您配置应用程序的日志通道，因此请务必查看每个可用通道及其选项。 我们将在下面回顾一些常见的选项。

默认情况下，Laravel 在记录日志消息时使用 stack 频道。stack 频道用于将多个日志频道聚合到一个频道中。有关构建堆栈的更多信息，请查看下面的文档。

默认情况下，Monolog 使用与当前环境相匹配的“频道名称”（例如 production 或 local）进行实例化。要更改此值，请向频道的配置中添加一个 name 选项：

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

可用频道驱动程序

每个日志频道都由一个“驱动程序”驱动。驱动程序确定实际记录日志消息的方式和位置。以下日志频道驱动程序在每个 Laravel 应用程序中都可用。大多数这些驱动程序的条目已经在应用程序的 config/logging.php 配置文件中存在，因此请务必查看此文件以熟悉其内容：

频道前提条件

在处理消息时，single和 daily 频道有三个可选配置选项：bubble，permission 和locking。

另外，可以通过 days 选项配置 daily 频道的保留策略：

papertrail 频道需要 host 和 port 配置选项。您可以从Papertrail获取这些值。

slack 频道需要一个 url 配置选项。此URL应该与您为Slack团队配置的incoming webhook的URL匹配。

默认情况下，Slack仅会接收 critical 级别及以上的日志；但是，您可以通过修改 config/logging.php 配置文件中您的Slack日志频道配置数组中的 level 配置选项来调整此设置。

记录弃用警告

PHP、Laravel和其他库通常会通知其用户，一些功能已被弃用，将在未来版本中删除。如果您想记录这些弃用警告，可以在应用程序的 config/logging.php 配置文件中指定您首选的 deprecations 日志频道：

copy
'deprecations' => env('LOG_DEPRECATIONS_CHANNEL', 'null'), 'channels' => [ ... ]

或者，您可以定义一个名为 deprecations 的日志通道。如果存在此名称的日志通道，则始终将其用于记录弃用：

copy
'channels' => [ 'deprecations' => [ 'driver' => 'single', 'path' => storage_path('logs/php-deprecation-warnings.log'), ], ],

构建日志堆栈

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

copy
'channels' => [ 'stack' => [ 'driver' => 'stack', 'channels' => ['syslog', 'slack'], ], 'syslog' => [ 'driver' => 'syslog', 'level' => 'debug', ], 'slack' => [ 'driver' => 'slack', 'url' => env('LOG_SLACK_WEBHOOK_URL'), 'username' => 'Laravel Log', 'emoji' => ':boom:', 'level' => 'critical', ], ],

让我们分解一下这个配置。首先，请注意我们的 stack 通道通过其 channels 选项聚合了两个其他通道：syslog 和 slack。因此，在记录消息时，这两个通道都有机会记录消息。但是，正如我们将在下面看到的那样，这些通道是否实际记录消息可能取决于消息的严重程度/“级别”。

请注意上面示例中 syslog 和 slack 通道配置中存在的 level 配置选项。此选项确定必须记录消息的最小“级别”。Laravel的日志服务采用Monolog，提供RFC 5424规范中定义的所有日志级别。按严重程度递减的顺序，这些日志级别是：emergency，alert，critical，error，warning，notice，info和debug。

在我们的配置中，如果我们使用 debug 方法记录消息：

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

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

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

写入日志消息

您可以使用 LogRFC 5424 规范 中定义的八个日志级别：emergency、alert、critical、error、warning、notice、info 和 debug：

copy
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 配置文件配置的默认日志渠道进行写入：

copy
<?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 { /** * Show the profile for the given user. */ public function show(string $id): View { Log::info('Showing the user profile for user: '.$id); return view('user.profile', [ 'user' => User::findOrFail($id) ]); } }

上下文信息

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

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

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

copy
<?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 ]); return $next($request)->header('Request-Id', $requestId); } }

如果要在_所有_日志频道之间共享上下文信息，则可以调用 Log::shareContext() 方法。此方法将向所有已创建的频道提供上下文信息，以及随后创建的任何频道。通常，shareContext 方法应从应用程序服务提供程序的 boot 方法中调用：

copy
use Illuminate\Support\Facades\Log; use Illuminate\Support\Str; class AppServiceProvider { /** * 启动任何应用程序服务。 */ public function boot(): void { Log::shareContext([ 'invocation-id' => (string) Str::uuid(), ]); } }

写入特定频道

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

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

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

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

还可以创建一个按需通道，方法是在运行时提供配置而无需将该配置包含在应用程序的 logging 配置文件中。为此，可以将配置数组传递给 Log 门面的 build 方法：

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

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

copy
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 实例后应有机会自定义（或“tap”）它。没有这些类应放置在何处的惯例位置，因此您可以在应用程序中创建一个目录以包含这些类：

copy
'single' => [ 'driver' => 'single', 'tap' => [App\Logging\CustomizeFormatter::class], 'path' => storage_path('logs/laravel.log'), 'level' => 'debug', ],

一旦你在通道上配置了 tap 选项，你就可以定义一个类来自定义你的 Monolog 实例。这个类只需要一个方法：__invoke，它接收一个 Illuminate\Log\Logger 实例。Illuminate\Log\Logger 实例代理所有方法调用到底层的 Monolog 实例：

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

创建 Monolog 处理程序通道

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

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

copy
'logentries' => [ 'driver' => 'monolog', 'handler' => Monolog\Handler\SyslogUdpHandler::class, 'with' => [ 'host' => 'my.logentries.internal.datahubhost.company.com', 'port' => '10000', ], ],

使用 monolog 驱动程序时，Monolog LineFormatter 将用作默认格式化程序。但是，你可以使用 formatter 和 formatter_with 配置选项自定义传递给处理程序的格式化程序类型：

copy
'browser' => [ 'driver' => 'monolog', 'handler' => Monolog\Handler\BrowserConsoleHandler::class, 'formatter' => Monolog\Formatter\HtmlFormatter::class, 'formatter_with' => [ 'dateFormat' => 'Y-m-d', ], ],

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

copy
'newrelic' => [ 'driver' => 'monolog', 'handler' => Monolog\Handler\NewRelicHandler::class, 'formatter' => 'default', ],

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

如果你想为 monolog 驱动定制处理器，请在通道的配置中加入processors 配置值。

copy
'memory' => [ 'driver' => 'monolog', 'handler' => Monolog\Handler\StreamHandler::class, '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 实例的工厂类的名称：

copy
'channels' => [ 'example-custom-channel' => [ 'driver' => 'custom', 'via' => App\Logging\CreateCustomLogger::class, ], ],

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