Laravel 13.x 中文文档

主题

Laravel Pulse ​

简介 ​

Laravel pulse 提供了对应用程序性能和使用情况的概览洞察。使用 Pulse，您可以追踪瓶颈，如慢作业和端点，找到最活跃的用户等。

如需深入调试单个事件，请查看 Laravel Telescope。

安装 ​

WARNING

Pulse 的第一方存储实现目前需要 MySQL、MariaDB 或 PostgreSQL 数据库。如果您使用不同的数据库引擎，则需要为 Pulse 数据使用单独的 MySQL、MariaDB 或 PostgreSQL 数据库。

您可以使用 Composer 包管理器安装 Pulse：

shell
composer require laravel/pulse

接下来，您应该使用 vendor:publish Artisan 命令发布 Pulse 配置和迁移文件：

shell
php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"

最后，您应该运行 migrate 命令以创建存储 Pulse 数据所需的表：

shell
php artisan migrate

运行 Pulse 的数据库迁移后，您可以通过 /pulse 路由访问 Pulse 仪表板。

NOTE

如果您不想将 Pulse 数据存储在应用程序的主数据库中，可以 指定专用的数据库连接。

配置 ​

Pulse 的许多配置选项可以使用环境变量控制。要查看可用选项、注册新记录器或配置高级选项，您可以发布 config/pulse.php 配置文件：

shell
php artisan vendor:publish --tag=pulse-config

仪表板 ​

授权 ​

可以通过 /pulse 路由访问 Pulse 仪表板。默认情况下，您只能在 local 环境中访问此仪表板，因此您需要通过自定义 'viewPulse' 授权门来配置生产环境的授权。您可以在应用程序的 app/Providers/AppServiceProvider.php 文件中完成此操作：

php
use App\Models\User;
use Illuminate\Support\Facades\Gate;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Gate::define('viewPulse', function (User $user) {
        return $user->isAdmin();
    });

    // ...
}

自定义 ​

可以通过发布仪表板视图来配置 Pulse 仪表板卡片和布局。仪表板视图将发布到 resources/views/vendor/pulse/dashboard.blade.php：

shell
php artisan vendor:publish --tag=pulse-dashboard

仪表板由 Livewire 驱动，允许您自定义卡片和布局，而无需重建任何 JavaScript 资源。

在此文件中，<x-pulse> 组件负责渲染仪表板并为卡片提供网格布局。如果您希望仪表板跨越屏幕的全宽，可以向组件提供 full-width 属性：

blade
<x-pulse full-width>
    ...
</x-pulse>

默认情况下，<x-pulse> 组件将创建一个 12 列网格，但您可以使用 cols 属性自定义此设置：

blade
<x-pulse cols="16">
    ...
</x-pulse>

每个卡片接受 cols 和 rows 属性来控制空间和位置：

blade
<livewire:pulse.usage cols="4" rows="2" />

大多数卡片还接受 expand 属性以显示完整卡片而不是滚动：

blade
<livewire:pulse.slow-queries expand />

解析用户 ​

对于显示用户信息的卡片，如应用程序使用卡片，Pulse 只会记录用户的 ID。渲染仪表板时，Pulse 将从默认 Authenticatable 模型解析 name 和 email 字段，并使用 Gravatar Web 服务显示头像。

您可以通过在应用程序的 App\Providers\AppServiceProvider 类中调用 Pulse::user 方法来自定义字段和头像。

user 方法接受一个闭包，该闭包将接收要显示的 Authenticatable 模型，并应返回包含用户 name、extra 和 avatar 信息的数组：

php
use Laravel\Pulse\Facades\Pulse;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Pulse::user(fn ($user) => [
        'name' => $user->name,
        'extra' => $user->email,
        'avatar' => $user->avatar_url,
    ]);

    // ...
}

NOTE

您可以通过实现 Laravel\Pulse\Contracts\ResolvesUsers 契约并在 Laravel 服务容器 中绑定它，来完全自定义如何捕获和检索经过身份验证的用户。

卡片 ​

服务器 ​

<livewire:pulse.servers /> 卡片显示运行 pulse:check 命令的所有服务器的系统资源使用情况。请参阅有关 服务器记录器 的文档以获取有关系统资源报告的更多信息。

如果您替换了基础设施中的服务器，您可能希望在给定持续时间后停止在 Pulse 仪表板中显示非活动服务器。您可以使用 ignore-after 属性完成此操作，该属性接受非活动服务器应从 Pulse 仪表板中移除的秒数。或者，您可以提供相对时间格式的字符串，如 1 hour 或 3 days and 1 hour：

blade
<livewire:pulse.servers ignore-after="3 hours" />

应用程序使用 ​

<livewire:pulse.usage /> 卡片显示向应用程序发出请求、分发作业和遇到慢请求的前 10 名用户。

如果您希望同时在屏幕上查看所有使用指标，可以多次包含该卡片并指定 type 属性：

blade
<livewire:pulse.usage type="requests" />
<livewire:pulse.usage type="slow_requests" />
<livewire:pulse.usage type="jobs" />

要了解如何自定义 Pulse 检索和显示用户信息的方式，请参阅我们关于 解析用户 的文档。

NOTE

如果您的应用程序收到大量请求或分发大量作业，您可能希望启用 采样。有关更多信息，请参阅 用户请求记录器、用户作业记录器 和 慢作业记录器 文档。

异常 ​

<livewire:pulse.exceptions /> 卡片显示应用程序中发生异常的频率和最近时间。默认情况下，异常根据异常类和发生位置进行分组。有关更多信息，请参阅 异常记录器 文档。

队列 ​

<livewire:pulse.queues /> 卡片显示应用程序中队列的吞吐量，包括排队、处理、已处理、释放和失败的作业数量。有关更多信息，请参阅 队列记录器 文档。

慢请求 ​

<livewire:pulse.slow-requests /> 卡片显示向应用程序发出的超过配置阈值（默认为 1,000ms）的传入请求。有关更多信息，请参阅 慢请求记录器 文档。

慢作业 ​

<livewire:pulse.slow-jobs /> 卡片显示应用程序中超过配置阈值（默认为 1,000ms）的排队作业。有关更多信息，请参阅 慢作业记录器 文档。

慢查询 ​

<livewire:pulse.slow-queries /> 卡片显示应用程序中超过配置阈值（默认为 1,000ms）的数据库查询。

默认情况下，慢查询根据 SQL 查询（不含绑定）和发生位置进行分组，但如果您希望仅按 SQL 查询分组，可以选择不捕获位置。

如果由于极大的 SQL 查询接收语法高亮而导致渲染性能问题，可以通过添加 without-highlighting 属性来禁用高亮：

blade
<livewire:pulse.slow-queries without-highlighting />

有关更多信息，请参阅 慢查询记录器 文档。

慢出站请求 ​

<livewire:pulse.slow-outgoing-requests /> 卡片显示使用 Laravel HTTP 客户端 发出的超过配置阈值（默认为 1,000ms）的出站请求。

默认情况下，条目将按完整 URL 分组。但是，您可能希望使用正则表达式规范化或分组类似的出站请求。有关更多信息，请参阅 慢出站请求记录器 文档。

缓存 ​

<livewire:pulse.cache /> 卡片显示应用程序的缓存命中和未命中统计信息，包括全局和单个键。

默认情况下，条目将按键分组。但是，您可能希望使用正则表达式规范化或分组类似的键。有关更多信息，请参阅 缓存交互记录器 文档。

捕获条目 ​

大多数 Pulse 记录器会根据 Laravel 分发的框架事件自动捕获条目。但是，服务器记录器 和某些第三方卡片必须定期轮询信息。要使用这些卡片，您必须在所有单独的应用程序服务器上运行 pulse:check 守护进程：

php
php artisan pulse:check

NOTE

要保持 pulse:check 进程在后台永久运行，您应该使用进程监视器（如 Supervisor）来确保命令不会停止运行。

由于 pulse:check 命令是一个长时间运行的进程，如果不重新启动，它将看不到代码库的更改。您应该在应用程序的部署过程中调用 pulse:restart 命令来优雅地重启命令：

shell
php artisan pulse:restart

NOTE

Pulse 使用 缓存 来存储重启信号，因此在使用此功能之前，您应该验证应用程序是否正确配置了缓存驱动程序。

记录器 ​

记录器负责从应用程序捕获条目以记录到 Pulse 数据库中。记录器在 Pulse 配置文件 的 recorders 部分注册和配置。

缓存交互 ​

CacheInteractions 记录器捕获有关应用程序中发生的 缓存 命中和未命中的信息，以在 缓存 卡片上显示。

您可以选择调整 采样率 和忽略的键模式。

您还可以配置键分组，以便将类似的键分组为单个条目。例如，您可能希望从缓存相同类型信息的键中删除唯一 ID。分组使用正则表达式配置，以「查找和替换」键的部分。配置文件中包含一个示例：

php
Recorders\CacheInteractions::class => [
    // ...
    'groups' => [
        // '/:\d+/' => ':*',
    ],
],

将使用第一个匹配的模式。如果没有模式匹配，则键将按原样捕获。

异常 ​

Exceptions 记录器捕获有关应用程序中发生的可报告异常的信息，以在 异常 卡片上显示。

您可以选择调整 采样率 和忽略的异常模式。您还可以配置是否捕获异常起源的位置。捕获的位置将显示在 Pulse 仪表板上，有助于追踪异常起源；但是，如果同一异常在多个位置发生，它将为每个唯一位置出现多次。

队列 ​

Queues 记录器捕获有关应用程序队列的信息，以在 队列 卡片上显示。

您可以选择调整 采样率 和忽略的作业模式。

慢作业 ​

SlowJobs 记录器捕获有关应用程序中发生的慢作业的信息，以在 慢作业 卡片上显示。

您可以选择调整慢作业阈值、采样率 和忽略的作业模式。

您可能有一些预期需要更长时间的作业。在这种情况下，您可以为每个作业配置阈值：

php
Recorders\SlowJobs::class => [
    // ...
    'threshold' => [
        '#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
        'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
    ],
],

如果没有正则表达式模式匹配作业的类名，则将使用 'default' 值。

慢出站请求 ​

SlowOutgoingRequests 记录器捕获有关使用 Laravel HTTP 客户端 发出的超过配置阈值的出站 HTTP 请求的信息，以在 慢出站请求 卡片上显示。

您可以选择调整慢出站请求阈值、采样率 和忽略的 URL 模式。

您可能有一些预期需要更长时间的出站请求。在这种情况下，您可以为每个请求配置阈值：

php
Recorders\SlowOutgoingRequests::class => [
    // ...
    'threshold' => [
        '#backup.zip$#' => 5000,
        'default' => env('PULSE_SLOW_OUTGOING_REQUESTS_THRESHOLD', 1000),
    ],
],

如果没有正则表达式模式匹配请求的 URL，则将使用 'default' 值。

您还可以配置 URL 分组，以便将类似的 URL 分组为单个条目。例如，您可能希望从 URL 路径中删除唯一 ID 或仅按域分组。分组使用正则表达式配置，以「查找和替换」URL 的部分。配置文件中包含一些示例：

php
Recorders\SlowOutgoingRequests::class => [
    // ...
    'groups' => [
        // '#^https://api\.github\.com/repos/.*$#' => 'api.github.com/repos/*',
        // '#^https?://([^/]*).*$#' => '\1',
        // '#/\d+#' => '/*',
    ],
],

将使用第一个匹配的模式。如果没有模式匹配，则 URL 将按原样捕获。

慢查询 ​

SlowQueries 记录器捕获应用程序中超过配置阈值的任何数据库查询，以在 慢查询 卡片上显示。

您可以选择调整慢查询阈值、采样率 和忽略的查询模式。您还可以配置是否捕获查询位置。捕获的位置将显示在 Pulse 仪表板上，有助于追踪查询起源；但是，如果在多个位置进行相同的查询，它将为每个唯一位置出现多次。

您可能有一些预期需要更长时间的查询。在这种情况下，您可以为每个查询配置阈值：

php
Recorders\SlowQueries::class => [
    // ...
    'threshold' => [
        '#^insert into `yearly_reports`#' => 5000,
        'default' => env('PULSE_SLOW_QUERIES_THRESHOLD', 1000),
    ],
],

如果没有正则表达式模式匹配查询的 SQL，则将使用 'default' 值。

慢请求 ​

Requests 记录器捕获向应用程序发出的请求的信息，以在 慢请求 和 应用程序使用 卡片上显示。

您可以选择调整慢路由阈值、采样率 和忽略的路径。

您可能有一些预期需要更长时间的请求。在这种情况下，您可以为每个请求配置阈值：

php
Recorders\SlowRequests::class => [
    // ...
    'threshold' => [
        '#^/admin/#' => 5000,
        'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
    ],
],

如果没有正则表达式模式匹配请求的 URL，则将使用 'default' 值。

服务器 ​

Servers 记录器捕获为应用程序提供动力的服务器的 CPU、内存和存储使用情况，以在 服务器 卡片上显示。此记录器需要在您希望监视的每个服务器上运行 pulse:check 命令。

每个报告的服务器必须具有唯一的名称。默认情况下，Pulse 将使用 PHP 的 gethostname 函数返回的值。如果您希望自定义此设置，可以设置 PULSE_SERVER_NAME 环境变量：

env
PULSE_SERVER_NAME=load-balancer

Pulse 配置文件还允许您自定义监视的目录。

用户作业 ​

UserJobs 记录器捕获有关在应用程序中分发作业的用户的信息，以在 应用程序使用 卡片上显示。

您可以选择调整 采样率 和忽略的作业模式。

用户请求 ​

UserRequests 记录器捕获有关向应用程序发出请求的用户的信息，以在 应用程序使用 卡片上显示。

您可以选择调整 采样率 和忽略的 URL 模式。

过滤 ​

正如我们所见，许多 记录器 提供了通过配置根据其值（如请求的 URL）「忽略」传入条目的能力。但是，有时根据其他因素（如当前经过身份验证的用户）过滤记录可能很有用。要过滤掉这些记录，您可以将闭包传递给 Pulse 的 filter 方法。通常，filter 方法应该在应用程序的 AppServiceProvider 的 boot 方法中调用：

php
use Illuminate\Support\Facades\Auth;
use Laravel\Pulse\Entry;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Value;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Pulse::filter(function (Entry|Value $entry) {
        return Auth::user()->isNotAdmin();
    });

    // ...
}

性能 ​

Pulse 旨在无需任何额外基础设施即可投入现有应用程序。但是，对于高流量应用程序，有几种方法可以消除 Pulse 可能对应用程序性能的影响。

使用不同的数据库 ​

对于高流量应用程序，您可能更愿意为 Pulse 使用专用的数据库连接，以避免影响应用程序数据库。