Appearance
Laravel Telescope
简介
Laravel Telescope 是 Laravel 本地开发环境的绝佳伴侣。Telescope 为你的应用程序提供了洞察力,包括进入应用程序的请求、异常、日志条目、数据库查询、排队的作业、邮件、通知、缓存操作、定时任务、变量转储等。
安装
你可以使用 Composer 包管理器将 Telescope 安装到你的 Laravel 项目中:
shell
composer require laravel/telescope
安装 Telescope 后,使用 telescope:install
Artisan 命令发布其资源和迁移文件。安装 Telescope 后,你还应该运行 migrate
命令以创建存储 Telescope 数据所需的表:
shell
php artisan telescope:install
php artisan migrate
最后,你可以通过 /telescope
路由访问 Telescope 仪表板。
仅本地安装
如果你只打算在本地使用 Telescope 来辅助开发,你可以使用 --dev
标志安装 Telescope:
shell
composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate
运行 telescope:install
后,你应该从应用程序的 bootstrap/providers.php
配置文件中删除 TelescopeServiceProvider
服务提供者注册。相反,在 App\Providers\AppServiceProvider
类的 register
方法中手动注册 Telescope 的服务提供者。我们将在当前环境为 local
时注册这些提供者:
php
/**
* 注册任何应用程序服务。
*/
public function register(): void
{
if ($this->app->environment('local')) {
$this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
$this->app->register(TelescopeServiceProvider::class);
}
}
最后,你还应该防止 Telescope 包被 自动发现,方法是在 composer.json
文件中添加以下内容:
json
"extra": {
"laravel": {
"dont-discover": [
"laravel/telescope"
]
}
},
配置
发布 Telescope 的资源后,其主要配置文件将位于 config/telescope.php
。此配置文件允许你配置你的 观察者选项。每个配置选项都包含其用途的描述,因此请务必仔细研究此文件。
如果需要,你可以使用 enabled
配置选项完全禁用 Telescope 的数据收集:
php
'enabled' => env('TELESCOPE_ENABLED', true),
数据清理
如果不进行清理,telescope_entries
表可能会迅速累积记录。为了缓解这一问题,你应该 安排 telescope:prune
Artisan 命令每天运行一次:
php
use Illuminate\Support\Facades\Schedule;
Schedule::command('telescope:prune')->daily();
默认情况下,所有超过 24 小时的条目都将被清理。你可以在调用命令时使用 hours
选项来确定保留 Telescope 数据的时长。例如,以下命令将删除所有超过 48 小时的记录:
php
use Illuminate\Support\Facades\Schedule;
Schedule::command('telescope:prune --hours=48')->daily();
仪表板授权
Telescope 仪表板可以通过 /telescope
路由访问。默认情况下,你只能在 local
环境中访问此仪表板。在你的 app/Providers/TelescopeServiceProvider.php
文件中,有一个 授权门 定义。此授权门控制了 非本地 环境中对 Telescope 的访问。你可以根据需要修改此门以限制对 Telescope 安装的访问:
php
use App\Models\User;
/**
* 注册 Telescope 门。
*
* 此门决定了非本地环境中谁可以访问 Telescope。
*/
protected function gate(): void
{
Gate::define('viewTelescope', function (User $user) {
return in_array($user->email, [
'taylor@laravel.com',
]);
});
}
WARNING
你应该确保在生产环境中将 APP_ENV
环境变量更改为 production
。否则,你的 Telescope 安装将公开可用。
升级 Telescope
升级到新的 Telescope 主要版本时,重要的是你仔细阅读 升级指南。
此外,当升级到任何新的 Telescope 版本时,你应该重新发布 Telescope 的资源:
shell
php artisan telescope:publish
为了保持资源最新并避免未来更新中的问题,你可以在应用程序的 composer.json
文件的 post-update-cmd
脚本中添加 vendor:publish --tag=laravel-assets
命令:
json
{
"scripts": {
"post-update-cmd": [
"@php artisan vendor:publish --tag=laravel-assets --ansi --force"
]
}
}
过滤
条目
你可以通过在 App\Providers\TelescopeServiceProvider
类中定义的 filter
闭包来过滤 Telescope 记录的���据。默认情况下,此闭包在 local
环境中记录所有数据,并在所有其他环境中记录异常、失败的作业、定时任务和带有监控标签的数据:
php
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
* 注册任何应用程序服务。
*/
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 将记录所有条目:
php
use Illuminate\Support\Collection;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
* 注册任何应用程序服务。
*/
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
方法:
php
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
* 注册任何应用程序服务。
*/
public function register(): void
{
$this->hideSensitiveRequestDetails();
Telescope::tag(function (IncomingEntry $entry) {
return $entry->type === 'request'
? ['status:'.$entry->content['response_status']]
: [];
});
}
可用的观察者
Telescope "观察者" 在请求或控制台命令执行时收集应用程序数据。你可以在 config/telescope.php
配置文件中自定义要启用的观察者列表:
php
'watchers' => [
Watchers\CacheWatcher::class => true,
Watchers\CommandWatcher::class => true,
...
],
一些观察者还允许你提供额外的自定义选项:
php
'watchers' => [
Watchers\QueryWatcher::class => [
'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
'slow' => 100,
],
...
],
批处理观察者
批处理观察者记录有关排队的 批处理,包括作业和连接信息。
缓存观察者
缓存观察者记录缓存键命中、未命中、更新和忘记时的数据。
命令观察者
命令观察者记录每次执行 Artisan 命令时的参数、选项、退出代码和输出。如果你想要排除某些命令不被观察者记录,你可以在 config/telescope.php
文件的 ignore
选项中指定该命令:
php
'watchers' => [
Watchers\CommandWatcher::class => [
'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
'ignore' => ['key:generate'],
],
...
],
Dump 观察者
Dump 观察者记录并在 Telescope 中显示你的变量转储。在 Laravel 中,可以使用全局 dump
函数转储变量。Dump 观察者选项卡必须在浏览器中打开,否则观察者将忽略转储。
事件观察者
事件观察者记录应用程序分派的任何 事件 的有效负载、监听器和广播数据。Laravel 框架的内部事件将被事件观察者忽略。
异常观察者
异常观察者记录应用程序抛出的任何可报告异常的数据和堆栈跟踪。
Gate 观察者
Gate 观察者记录应用程序执行的 gate 和策略 检查的数据和结果。如果你想要排除某些能力不被观察者记录,你可以在 config/telescope.php
文件的 ignore_abilities
选项中指定这些能力:
php
'watchers' => [
Watchers\GateWatcher::class => [
'enabled' => env('TELESCOPE_GATE_WATCHER', true),
'ignore_abilities' => ['viewNova'],
],
...
],
HTTP 客户端观察者
HTTP 客户端观察者记录应用程序发出的所有 HTTP 客户端请求。
任务观察者
任务观察者记录应用程序分派的任何 任务 的数据和状态。
日志观察者
日志观察者记录应用程序写入的任何 日志数据。
默认情况下,Telescope 只会记录 error
级别及以上的日志。但是,你可以修改应用程序的 config/telescope.php
配置文件中的 level
选项来修改此行为:
php
'watchers' => [
Watchers\LogWatcher::class => [
'enabled' => env('TELESCOPE_LOG_WATCHER', true),
'level' => 'debug',
],
// ...
],
邮件观察者
邮件观察者允许你在浏览器中预览应用程序发送的 邮件 以及它们相关的数据。你还可以将邮件下载为 .eml
文件。
模型观察者
模型观察者在分派 Eloquent 模型事件 时记录模型更改。你可以通过观察者的 events
选项指定要记录的模型事件:
php
'watchers' => [
Watchers\ModelWatcher::class => [
'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
'events' => ['eloquent.created*', 'eloquent.updated*'],
],
...
],
如果你想要记录给定请求期间实例化的模型数量,请启用 hydrations
选项:
php
'watchers' => [
Watchers\ModelWatcher::class => [
'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
'events' => ['eloquent.created*', 'eloquent.updated*'],
'hydrations' => true,
],
...
],
通知观察者
通知观察者记录应用程序发送的所有 通知。如果通知触发了电子邮件并且你启用了邮件观察者,该电子邮件也将在邮件观察者屏幕上可用于预览。
查询观察者
查询观察者记录应用程序执行的所有查询的原始 SQL、绑定和执行时间。观察者还会将超过 100 毫秒的任何查询标记为 slow
。你可以使用观察者的 slow
选项自定义慢查询阈值:
php
'watchers' => [
Watchers\QueryWatcher::class => [
'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
'slow' => 50,
],
...
],
Redis 观察者
Redis 观察者记录应用程序执行的所有 Redis 命令。如果你使用 Redis 进行缓存,缓存命令也将由 Redis 观察者记录。
请求观察者
请求观察者记录应用程序处理的任何请求的请求、标头、会话和响应数据。你可以通过 size_limit
(以千字节为单位) 选项限制记录的响应数据:
php
'watchers' => [
Watchers\RequestWatcher::class => [
'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
],
...
],
调度观察者
调度观察者记录应用程序运行的任何 定时任务 的命令和输出。
视图观察者
视图观察者记录渲染视图时使用的 视图 名称、路径、数据和 "composers"。
显示用户头像
Telescope 仪表板显示保存给定条目时经过身份验证的用户的用户头像。默认情况下,Telescope 将使用 Gravatar 网络服务检索头像。但是,你可以在 App\Providers\TelescopeServiceProvider
类中注册一个回调来自定义头像 URL。回调将接收用户的 ID 和电子邮件地址,并应返回用户的头像图像 URL:
php
use App\Models\User;
use Laravel\Telescope\Telescope;
/**
* 注册任何应用程序服务。
*/
public function register(): void
{
// ...
Telescope::avatar(function (string $id, string $email) {
return '/avatars/'.User::find($id)->avatar_path;
});
}