后盾人

Appearance

日志记录 ​

简介 ​

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

Laravel 的日志记录基于"通道"。每个通道代表一种特定的写入日志信息的方式。例如,single 通道将日志文件写入单个日志文件,而 slack 通道将日志消息发送到 Slack。根据消息的严重程度,日志消息可以写入多个通道。

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

配置 ​

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

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

可用的通道驱动 ​

每个日志通道都由"驱动程序"提供支持。驱动程序决定了日志消息实际记录的方式和位置。以下日志通道驱动程序在每个 Laravel 应用程序中都可用。应用程序的 config/logging.php 配置文件中已经存在这些驱动程序中的大多数条目,因此请务必查看此文件以熟悉其内容:

名称描述
custom调用指定工厂来创建通道的驱动程序。
daily基于 Monolog 的 RotatingFileHandler 驱动程序,每天轮换。
errorlog基于 Monolog 的 ErrorLogHandler 驱动程序。
monologMonolog 工厂驱动程序,可以使用任何支持的 Monolog 处理程序。
papertrail基于 Monolog 的 SyslogUdpHandler 驱动程序。
single基于单个文件或路径的日志通道 (StreamHandler)。
slack基于 Monolog 的 SlackWebhookHandler 驱动程序。
stack用于创建"多通道"通道的包装器。
syslog基于 Monolog 的 SyslogHandler 驱动程序。

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应保留每日日志文件的天数。7

配置 Papertrail 通道 ​

papertrail 通道需要 host 和 port 配置选项。这些选项可以通过 PAPERTRAIL_URL 和 PAPERTRAIL_PORT 环境变量定义。您可以从 Papertrail 获取这些值。

配置 Slack 通道 ​

slack 通道需要 url 配置选项。此值可以通过 LOG_SLACK_WEBHOOK_URL 环境变量定义。此 URL 应与您为 Slack 团队配置的 incoming 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'],
        '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 配置选项。此选项确定消息的最低"级别"必须是多少才能被通道记录。Monolog,驱动 Laravel 的日志服务,提供了 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 facade 将信息写入日志。如前所述,日志记录器提供了 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\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}', ['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 facade 的 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

如果您需要在处理排队作业时共享日志上下文,您可以利用 job middleware。

写入到特定通道 ​

有时您可能希望将消息记录到应用程序的默认通道之外的通道。您可以使用 Log facade 的 channel 方法检索并记录配置文件中定义的任何通道:

php
    use Illuminate\Support\Facades\Log;

    Log::channel('slack')->info('Something happened!');

如果您希望创建一个按需日志堆栈,包含多个通道,您可以使用 stack 方法:

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

按需通道 ​

您还可以创建一个按需通道,方法是在运行时提供配置,而不是在应用程序的 logging 配置文件中定义该配置。要实现此目的,您可以将配置数组传递给 Log facade 的 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 实例创建后对其进行自定义(或"tap"进去)。这些类没有约定的位置,因此您可以在应用程序中创建一个目录来包含这些类:

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

所有"tap"类都由 service container 解析,因此它们所需的任何构造函数依赖项都将自动注入。

创建 Monolog 处理程序通道 ​

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

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

php
    '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 配置选项自定义传递给处理程序的格式化器类型:

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,
         'with' => [
             'stream' => 'php://stderr',
         ],
         'processors' => [
             // 简单语法...
             Monolog\Processor\MemoryUsageProcessor::class,

             // 带选项的...
             [
                '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 需要 PHP 8.2+ 和 PCNTL 扩展。

要开始,使用 Composer 包管理器将 Pail 安装到您的项目中:

bash
composer require 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

后盾人版权所有 © 2018-2024 创作不易请尊重他人劳动成果，未经授权禁止转载！