Laravel Telescope

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

简介

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

安装

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

1composer require laravel/telescope

composer require laravel/telescope

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

1php artisan telescope:install
2 
3php artisan migrate

php artisan telescope:install

php artisan migrate

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

仅限本地安装

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

1composer require laravel/telescope --dev
2 
3php artisan telescope:install
4 
5php artisan migrate

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

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

 1/**
 2 * Register any application services.
 3 */
 4public function register(): void
 5{
 6    if ($this->app->environment('local') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
 7        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
 8        $this->app->register(TelescopeServiceProvider::class);
 9    }
10}

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

最后，您还应该通过在 composer.json 文件中添加以下内容，防止 Telescope 包被自动发现

1"extra": {
2    "laravel": {
3        "dont-discover": [
4            "laravel/telescope"
5        ]
6    }
7},

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

配置

发布 Telescope 的资源文件后，其主要配置文件将位于 config/telescope.php。此配置文件允许您配置监视器选项。每个配置选项都包含了其用途的说明，因此请务必仔细阅读此文件。

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

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

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

数据清理

如果不进行清理，telescope_entries 表会非常迅速地积累记录。为了缓解这种情况，您应该计划 telescope:prune Artisan 命令每天运行一次

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

use Illuminate\Support\Facades\Schedule;

Schedule::command('telescope:prune')->daily();

默认情况下，所有超过 24 小时的条目都会被清理。您可以在调用该命令时使用 hours 选项来决定保留多久的 Telescope 数据。例如，以下命令将删除 48 小时前创建的所有记录

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

use Illuminate\Support\Facades\Schedule;

Schedule::command('telescope:prune --hours=48')->daily();

仪表板授权

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

 1use App\Models\User;
 2 
 3/**
 4 * Register the Telescope gate.
 5 *
 6 * This gate determines who can access Telescope in non-local environments.
 7 */
 8protected function gate(): void
 9{
10    Gate::define('viewTelescope', function (User $user) {
11        return in_array($user->email, [
12            '[email protected]',
13        ]);
14    });
15}

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 的资源文件

1php artisan telescope:publish

php artisan telescope:publish

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

1{
2    "scripts": {
3        "post-update-cmd": [
4            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
5        ]
6    }
7}

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

过滤

条目

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

 1use Laravel\Telescope\IncomingEntry;
 2use Laravel\Telescope\Telescope;
 3 
 4/**
 5 * Register any application services.
 6 */
 7public function register(): void
 8{
 9    $this->hideSensitiveRequestDetails();
10 
11    Telescope::filter(function (IncomingEntry $entry) {
12        if ($this->app->environment('local')) {
13            return true;
14        }
15 
16        return $entry->isReportableException() ||
17            $entry->isFailedJob() ||
18            $entry->isScheduledTask() ||
19            $entry->isSlowQuery() ||
20            $entry->hasMonitoredTag();
21    });
22}

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 将记录所有条目

 1use Illuminate\Support\Collection;
 2use Laravel\Telescope\IncomingEntry;
 3use Laravel\Telescope\Telescope;
 4 
 5/**
 6 * Register any application services.
 7 */
 8public function register(): void
 9{
10    $this->hideSensitiveRequestDetails();
11 
12    Telescope::filterBatch(function (Collection $entries) {
13        if ($this->app->environment('local')) {
14            return true;
15        }
16 
17        return $entries->contains(function (IncomingEntry $entry) {
18            return $entry->isReportableException() ||
19                $entry->isFailedJob() ||
20                $entry->isScheduledTask() ||
21                $entry->isSlowQuery() ||
22                $entry->hasMonitoredTag();
23            });
24    });
25}

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 允许您通过“标签”搜索条目。通常，标签是 Eloquent 模型类名或已认证的用户 ID，Telescope 会自动将它们添加到条目中。有时，您可能希望将自己的自定义标签附加到条目中。为此，您可以使用 Telescope::tag 方法。tag 方法接受一个返回标签数组的闭包。闭包返回的标签将与 Telescope 自动附加到条目的任何标签合并。通常，您应该在 App\Providers\TelescopeServiceProvider 类的 register 方法中调用 tag 方法

 1use Laravel\Telescope\EntryType;
 2use Laravel\Telescope\IncomingEntry;
 3use Laravel\Telescope\Telescope;
 4 
 5/**
 6 * Register any application services.
 7 */
 8public function register(): void
 9{
10    $this->hideSensitiveRequestDetails();
11 
12    Telescope::tag(function (IncomingEntry $entry) {
13        return $entry->type === EntryType::REQUEST
14            ? ['status:'.$entry->content['response_status']]
15            : [];
16    });
17}

use Laravel\Telescope\EntryType;
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 === EntryType::REQUEST
            ? ['status:'.$entry->content['response_status']]
            : [];
    });
}

可用监视器

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

1'watchers' => [
2    Watchers\CacheWatcher::class => true,
3    Watchers\CommandWatcher::class => true,
4    // ...
5],

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

某些监视器还允许您提供额外的自定义选项

1'watchers' => [
2    Watchers\QueryWatcher::class => [
3        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
4        'slow' => 100,
5    ],
6    // ...
7],

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

批处理监视器

批处理监视器记录有关排队批处理的信息，包括任务和连接信息。

缓存监视器

缓存监视器在缓存键命中、未命中、更新和删除时记录数据。

命令监视器

命令监视器在执行 Artisan 命令时记录参数、选项、退出代码和输出。如果您希望排除某些不被监视器记录的命令，可以在 config/telescope.php 文件中的 ignore 选项中指定这些命令

1'watchers' => [
2    Watchers\CommandWatcher::class => [
3        'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
4        'ignore' => ['key:generate'],
5    ],
6    // ...
7],

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

Dump 监视器

Dump 监视器在 Telescope 中记录并显示您的变量转储。使用 Laravel 时，可以使用全局 dump 函数转储变量。必须在浏览器中打开 Dump 监视器选项卡，转储才会被记录，否则监视器将忽略这些转储。

事件监视器

事件监视器记录应用程序分发的任何事件的有效载荷、监听器和广播数据。Laravel 框架的内部事件会被事件监视器忽略。

异常监视器

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

Gate 监视器

Gate 监视器记录应用程序进行的门卫（Gate）和策略（Policy）检查的数据和结果。如果您希望排除某些不被监视器记录的权限验证，可以在 config/telescope.php 文件中的 ignore_abilities 选项中指定它们

1'watchers' => [
2    Watchers\GateWatcher::class => [
3        'enabled' => env('TELESCOPE_GATE_WATCHER', true),
4        'ignore_abilities' => ['viewNova'],
5    ],
6    // ...
7],

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

HTTP 客户端监视器

HTTP 客户端监视器记录应用程序发出的外部 HTTP 请求。

任务监视器

任务监视器记录应用程序分发的任何任务的数据和状态。

日志监视器

日志监视器记录应用程序写入的任何日志数据。

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

1'watchers' => [
2    Watchers\LogWatcher::class => [
3        'enabled' => env('TELESCOPE_LOG_WATCHER', true),
4        'level' => 'debug',
5    ],
6 
7    // ...
8],

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

    // ...
],

邮件监视器

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

模型监视器

模型监视器在每次分发 Eloquent 模型事件时记录模型更改。您可以通过监视器的 events 选项指定要记录哪些模型事件

1'watchers' => [
2    Watchers\ModelWatcher::class => [
3        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
4        'events' => ['eloquent.created*', 'eloquent.updated*'],
5    ],
6    // ...
7],

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

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

1'watchers' => [
2    Watchers\ModelWatcher::class => [
3        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
4        'events' => ['eloquent.created*', 'eloquent.updated*'],
5        'hydrations' => true,
6    ],
7    // ...
8],

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

通知监视器

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

查询监视器

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

1'watchers' => [
2    Watchers\QueryWatcher::class => [
3        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
4        'slow' => 50,
5    ],
6    // ...
7],

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

Redis 监视器

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

请求监视器

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

1'watchers' => [
2    Watchers\RequestWatcher::class => [
3        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
4        'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
5    ],
6    // ...
7],

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

 1use App\Models\User;
 2use Laravel\Telescope\Telescope;
 3 
 4/**
 5 * Register any application services.
 6 */
 7public function register(): void
 8{
 9    // ...
10 
11    Telescope::avatar(function (?string $id, ?string $email) {
12        return ! is_null($id)
13            ? '/avatars/'.User::find($id)->avatar_path
14            : '/generic-avatar.jpg';
15    });
16}

use App\Models\User;
use Laravel\Telescope\Telescope;

/**
 * Register any application services.
 */
public function register(): void
{
    // ...

    Telescope::avatar(function (?string $id, ?string $email) {
        return ! is_null($id)
            ? '/avatars/'.User::find($id)->avatar_path
            : '/generic-avatar.jpg';
    });
}

Laravel Telescope

简介

安装

仅限本地安装

配置

数据清理

仪表板授权

升级 Telescope

过滤

条目

批处理

标签

可用监视器

批处理监视器

缓存监视器

命令监视器

Dump 监视器

事件监视器

异常监视器

Gate 监视器

HTTP 客户端监视器

任务监视器

日志监视器

邮件监视器

模型监视器

通知监视器

查询监视器

Redis 监视器

请求监视器

调度监视器

视图监视器

显示用户头像

在此页面上

产品

Packages

资源

合作伙伴