Laravel Telescope

简介
安装
升级 Telescope
过滤
- 条目
- 批处理
标签
可用观察器
显示用户头像

简介

Laravel Telescope 是你本地 Laravel 开发环境的绝佳伴侣。Telescope 可以深入了解进入你应用程序的请求、异常、日志条目、数据库查询、排队的作业、邮件、通知、缓存操作、计划任务、变量转储等等。

安装

你可以使用 Composer 包管理器将 Telescope 安装到你的 Laravel 项目中

composer require laravel/telescope

安装 Telescope 后，使用 telescope:install Artisan 命令发布其资源和迁移。安装 Telescope 后，还应运行 migrate 命令，以便创建存储 Telescope 数据所需的表

php artisan telescope:install
 
php artisan migrate

最后，你可以通过 /telescope 路由访问 Telescope 仪表盘。

仅限本地安装

如果你计划仅使用 Telescope 来辅助本地开发，则可以使用 --dev 标志安装 Telescope

composer require laravel/telescope --dev
 
php artisan telescope:install
 
php artisan migrate

运行 telescope:install 后，你应该从应用程序的 bootstrap/providers.php 配置文件中删除 TelescopeServiceProvider 服务提供者注册。相反，请在你的 App\Providers\AppServiceProvider 类的 register 方法中手动注册 Telescope 的服务提供者。我们将确保当前环境为 local，然后再注册提供者

/**
 * Register any application services.
 */
public function register(): void
{
    if ($this->app->environment('local')) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

最后，你还应通过将以下内容添加到你的 composer.json 文件中，来防止 Telescope 包被自动发现

"extra": {
    "laravel": {
        "dont-discover": [
            "laravel/telescope"
        ]
    }
},

配置

发布 Telescope 的资源后，其主配置文件将位于 config/telescope.php。此配置文件允许你配置观察器选项。每个配置选项都包含对其用途的描述，因此请务必彻底浏览此文件。

如果需要，你可以使用 enabled 配置选项完全禁用 Telescope 的数据收集

'enabled' => env('TELESCOPE_ENABLED', true),

数据修剪

如果不进行修剪，telescope_entries 表会很快累积记录。为了缓解这种情况，你应该计划每天运行 telescope:prune Artisan 命令

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('telescope:prune')->daily();

默认情况下，将修剪所有超过 24 小时的条目。调用命令时，可以使用 hours 选项来确定保留 Telescope 数据的时间。例如，以下命令将删除所有在 48 小时前创建的记录

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('telescope:prune --hours=48')->daily();

仪表盘授权

可以通过 /telescope 路由访问 Telescope 仪表盘。默认情况下，你只能在 local 环境中访问此仪表盘。在你的 app/Providers/TelescopeServiceProvider.php 文件中，有一个授权门控定义。此授权门控控制在非本地环境中对 Telescope 的访问。你可以根据需要随意修改此门控，以限制对你的 Telescope 安装的访问

use App\Models\User;
 
/**
 * Register the Telescope gate.
 *
 * This gate determines who can access Telescope in non-local environments.
 */
protected function gate(): void
{
    Gate::define('viewTelescope', function (User $user) {
        return in_array($user->email, [
            '[email protected]',
        ]);
    });
}

你应该确保将你的 APP_ENV 环境变量在生产环境中更改为 production。否则，你的 Telescope 安装将公开可用。

升级 Telescope

升级到新的 Telescope 主要版本时，请务必仔细查看升级指南。

此外，当升级到任何新的 Telescope 版本时，都应重新发布 Telescope 的资源

php artisan telescope:publish

为了保持资源为最新版本并避免将来更新中出现问题，你可以将 vendor:publish --tag=laravel-assets 命令添加到应用程序的 composer.json 文件中的 post-update-cmd 脚本中

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ]
    }
}

过滤

条目

你可以通过在你的 App\Providers\TelescopeServiceProvider 类中定义的 filter 闭包来过滤 Telescope 记录的数据。默认情况下，此闭包会记录 local 环境中的所有数据以及所有其他环境中的异常、失败的作业、计划任务和具有监控标签的数据

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
 
/**
 * Register any application services.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();
 
    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->environment('local')) {
            return true;
        }
 
        return $entry->isReportableException() ||
            $entry->isFailedJob() ||
            $entry->isScheduledTask() ||
            $entry->isSlowQuery() ||
            $entry->hasMonitoredTag();
    });
}

批处理

虽然 filter 闭包会过滤单个条目的数据，但你可以使用 filterBatch 方法注册一个闭包，该闭包会过滤给定请求或控制台命令的所有数据。如果闭包返回 true，则 Telescope 会记录所有条目

use Illuminate\Support\Collection;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
 
/**
 * Register any application services.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();
 
    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->environment('local')) {
            return true;
        }
 
        return $entries->contains(function (IncomingEntry $entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->isSlowQuery() ||
                $entry->hasMonitoredTag();
            });
    });
}

Telescope 允许你按“标签”搜索条目。通常，标签是 Telescope 自动添加到条目中的 Eloquent 模型类名称或经过身份验证的用户 ID。有时，你可能希望将你自己的自定义标签附加到条目。为此，你可以使用 Telescope::tag 方法。tag 方法接受一个闭包，该闭包应返回一个标签数组。闭包返回的标签将与 Telescope 自动附加到条目的任何标签合并。通常，你应该在 App\Providers\TelescopeServiceProvider 类的 register 方法中调用 tag 方法

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
 
/**
 * Register any application services.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();
 
    Telescope::tag(function (IncomingEntry $entry) {
        return $entry->type === 'request'
                    ? ['status:'.$entry->content['response_status']]
                    : [];
    });
 }

可用观察器

当执行请求或控制台命令时，Telescope“观察器”会收集应用程序数据。你可以在你的 config/telescope.php 配置文件中自定义你想要启用的观察器列表

'watchers' => [
    Watchers\CacheWatcher::class => true,
    Watchers\CommandWatcher::class => true,
    ...
],

某些观察器还允许你提供其他自定义选项

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,
    ],
    ...
],

批处理观察器

批处理观察器记录有关排队的批处理的信息，包括作业和连接信息。

缓存观察器

当命中、错过、更新和遗忘缓存键时，缓存观察器会记录数据。

命令观察器

命令观察器会记录每次执行 Artisan 命令时的参数、选项、退出代码和输出。如果想要从观察器记录中排除某些命令，可以在你的 config/telescope.php 文件中的 ignore 选项中指定该命令

'watchers' => [
    Watchers\CommandWatcher::class => [
        'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
        'ignore' => ['key:generate'],
    ],
    ...
],

转储观察器

转储观察器记录并显示 Telescope 中的变量转储。使用 Laravel 时，可以使用全局 dump 函数转储变量。转储观察器选项卡必须在浏览器中打开才能记录转储，否则，观察器将忽略转储。

事件观察器

事件观察器记录你的应用程序分派的任何事件的有效负载、侦听器和广播数据。Laravel 框架的内部事件将被事件观察器忽略。

异常观察器

异常观察器记录应用程序抛出的任何可报告异常的数据和堆栈跟踪。

门控观察器

门控观察器会记录你的应用程序对门控和策略检查的数据和结果。如果想要从观察器记录中排除某些功能，可以在你的 config/telescope.php 文件中的 ignore_abilities 选项中指定这些功能

'watchers' => [
    Watchers\GateWatcher::class => [
        'enabled' => env('TELESCOPE_GATE_WATCHER', true),
        'ignore_abilities' => ['viewNova'],
    ],
    ...
],

HTTP 客户端观察器

HTTP 客户端观察器会记录你的应用程序发出的传出 HTTP 客户端请求。

作业观察器

作业观察器记录你的应用程序分派的任何作业的数据和状态。

日志观察器

日志观察器会记录你的应用程序编写的任何日志的日志数据。

默认情况下，Telescope 只会记录 error 级别及以上的日志。但是，您可以在应用程序的 config/telescope.php 配置文件中修改 level 选项来更改此行为。

'watchers' => [
    Watchers\LogWatcher::class => [
        'enabled' => env('TELESCOPE_LOG_WATCHER', true),
        'level' => 'debug',
    ],
 
    // ...
],

邮件观察器

邮件监视器允许您在浏览器中预览应用程序发送的电子邮件及其相关数据。您还可以将电子邮件下载为 .eml 文件。

模型观察器

当 Eloquent 模型事件被触发时，模型监视器会记录模型更改。您可以通过监视器的 events 选项指定应该记录哪些模型事件。

'watchers' => [
    Watchers\ModelWatcher::class => [
        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
        'events' => ['eloquent.created*', 'eloquent.updated*'],
    ],
    ...
],

如果您想记录在给定请求期间水合的模型数量，请启用 hydrations 选项。

'watchers' => [
    Watchers\ModelWatcher::class => [
        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
        'events' => ['eloquent.created*', 'eloquent.updated*'],
        'hydrations' => true,
    ],
    ...
],

通知观察器

通知监视器会记录应用程序发送的所有通知。如果通知触发了电子邮件，并且您启用了邮件监视器，那么该电子邮件也可以在邮件监视器屏幕上预览。

查询观察器

查询监视器会记录应用程序执行的所有查询的原始 SQL、绑定和执行时间。该监视器还会将任何慢于 100 毫秒的查询标记为 slow。您可以使用监视器的 slow 选项自定义慢查询阈值。

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 50,
    ],
    ...
],

Redis 观察器

Redis 监视器会记录应用程序执行的所有 Redis 命令。如果您使用 Redis 进行缓存，缓存命令也会被 Redis 监视器记录。

请求观察器

请求监视器会记录与应用程序处理的任何请求相关的请求、标头、会话和响应数据。您可以通过 size_limit（以千字节为单位）选项来限制记录的响应数据大小。

'watchers' => [
    Watchers\RequestWatcher::class => [
        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
        'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
    ],
    ...
],

use App\Models\User;
use Laravel\Telescope\Telescope;
 
/**
 * Register any application services.
 */
public function register(): void
{
    // ...
 
    Telescope::avatar(function (string $id, string $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}

Laravel Telescope

简介

安装

仅限本地安装

配置

数据修剪

仪表盘授权

升级 Telescope

过滤

条目

批处理

标签

可用观察器

批处理观察器

缓存观察器

命令观察器

转储观察器

事件观察器

异常观察器

门控观察器

HTTP 客户端观察器

作业观察器

日志观察器

邮件观察器

模型观察器

通知观察器

查询观察器

Redis 观察器

请求观察器

计划观察器

视图观察器

显示用户头像