# Laravel Telescope - [简介](#introduction) - [安装](#installation) - [配置](#configuration) - [数据修改](#data-pruning) - [数据迁移](#migration-customization) - [仪表板授权](#dashboard-authorization) - [过滤](#filtering) - [单项过滤](#filtering-entries) - [批量过滤](#filtering-batches) - [标记](#tagging) - [可用的监听](#available-watchers) - [缓存监听](#cache-watcher) - [命令监听](#command-watcher) - [储存监听](#dump-watcher) - [事件监听](#event-watcher) - [异常监听](#exception-watcher) - [Gate 监听](#gate-watcher) - [进程监听](#job-watcher) - [日志监听](#log-watcher) - [邮件监听](#mail-watcher) - [模型监听](#model-watcher) - [消息通知监听](#notification-watcher) - [数据查询监听](#query-watcher) - [Redis 监听](#redis-watcher) - [请求监听](#request-watcher) - [定时任务监听](#schedule-watcher) ## 简介 Larave Telescope 是 Laravel 框架的优雅调试助手。Telescope 可深入了解进入应用程序的请求、异常、日志条目、数据库查询、排队作业、邮件、通知、缓存操作、计划任务、变量转储等。Telescope 是您本地 Laravel 开发环境的绝佳伴侣。
## 安装 你可以使用 Composer 在 Laravel 项目中安装 Telescope 扩展: composer require laravel/telescope:^3.0 安装 Telescope 后,可以在 Artisan 使用 `telescope:install` 命令来配置扩展实例。安装 Telescope 后,还应运行 `migrate` 命令: php artisan telescope:install php artisan migrate #### 更新 Telescope 更新 Telescope 时,您应该重新配置加载 Telescope 实例: php artisan telescope:publish ### 仅在特定环境中安装 如果您打算仅使用 Telescope 来协助您的本地开发。可以使用 `--dev` 标志安装 Telescope: composer require laravel/telescope --dev 运行 `telescope:install` 后,您应该从 `app` 配置文件中删除 `TelescopeServiceProvider` 服务提供注册。相反,在 `AppServiceProvider` 的 `register` 方法中手动注册服务: /** * 注册应用服务。 * * @return void */ public function register() { if ($this->app->isLocal()) { $this->app->register(TelescopeServiceProvider::class); } } ### 定制数据迁移 如果您不打算使用 Telescope 的默认迁移,则应该在 `AppServiceProvider` 的 `register` 方法中调用 `Telescope::ignoreMigrations` 方法。您可以使用 `php artisan vendor:publish --tag=telescope-migrations`命令导出默认迁移。 ### 配置 使用 Telescope,其主要配置文件将位于 `config/telescope.php`。此配置文件允许您配置监听程序选项,每个配置选项都包含其用途说明,因此请务必彻底浏览此文件。 如果需要,您可以使用 `enabled` 配置选项完全禁用 Telescope 的数据收集: 'enabled' => env('TELESCOPE_ENABLED', true), ### 数据修改 有了数据修改,`telescope_entries` 表可以非常快速地累积记录。为了缓解这个问题,你应该使用 Artisan 每天运行 `telescope:prune` 命令: $schedule->command('telescope:prune')->daily(); 默认情况下,将获取超过 24 小时的所有数据。在调用命令时可以使用 `hours` 选项来确定保留 Telescope 数据的时间。例如,以下命令将删除 48 小时前创建的所有记录: $schedule->command('telescope:prune --hours=48')->daily(); ## 仪表板授权 Telescope 在 `/telescope` 处显示仪表板。默认情况下,您只能在 `本地` 环境中访问此仪表板。在你的 `app/Providers/TelescopeServiceProvider.php` 文件中,有一个 `gate` 方法。此授权能控制在 **非本地** 环境中对 Telescope 的访问。您可以根据需要随意修改此权限限制以对 Telescope 安装和访问: /** * 注册 Telescope gate. * * 使用 Gate 决定谁可以在非本地环境中访问 Telescope。 * * @return void */ protected function gate() { Gate::define('viewTelescope', function ($user) { return in_array($user->email, [ 'taylor@laravel.com', ]); }); } ## 过滤 ### 单项过滤 您可以通过在 `TelescopeServiceProvider` 中注册的 `filter` 回调来过滤 Telescope 记录的数据。默认情况下,此回调会记录 `本地` 环境中的所有数据以及所有其他环境中的异常、进程中断、计划任务和带有受监控标记的数据: /** * 注册应用服务 * * @return void */ public function register() { $this->hideSensitiveRequestDetails(); Telescope::filter(function (IncomingEntry $entry) { if ($this->app->isLocal()) { return true; } return $entry->isReportableException() || $entry->isFailedJob() || $entry->isScheduledTask() || $entry->hasMonitoredTag(); }); } ### 批量过滤 虽然 `filter` 回调过滤单个条目的数据,但您可以使用 `filterBatch` 方法注册一个回调,该回调过滤给定请求或控制台命令的所有数据。如果回调返回 `true` ,则所有数据都由 Telescope 记录: use Illuminate\Support\Collection; /** * 注册应用服务 * * @return void */ public function register() { $this->hideSensitiveRequestDetails(); Telescope::filterBatch(function (Collection $entries) { if ($this->app->isLocal()) { return true; } return $entries->contains(function ($entry) { return $entry->isReportableException() || $entry->isFailedJob() || $entry->isScheduledTask() || $entry->hasMonitoredTag(); }); }); } ## 标签 `Telescope` 允许你通过 `tag` 搜索条目。通常,标签是 `Eloquent` 的模型类名或经过身份验证的用户id,这些标签会自动添加到条目中。有时,您可能希望将自己的自定义标签附加到条目中。你可以使用 `telescope::tag` 方法。 `tag` 方法接受一个回调,该回调应返回一个标签数组。回调返回的标签将与 `telescope` 自动附加到条目的任何标签合并。您应该在`TelescopeServiceProvider` 中调用`tag`方法: use Laravel\Telescope\Telescope; /** * 注册应用服务 * * @return void */ public function register() { $this->hideSensitiveRequestDetails(); Telescope::tag(function (IncomingEntry $entry) { if ($entry->type === 'request') { return ['status:'.$entry->content['response_status']]; } return []; }); } ## 可用的监听 当在控制台执行命令或处理请求时,`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 框架的内部事件。 ### 异常监听 异常监听器记录应用程序引发的任何可报告异常的数据和堆栈跟踪。 ### Gate 监听 Gate 监听器记录您的应用程序的 Gate 和策略检查的数据和结果。如果您希望将某些能力排除在监听器的记录之外,您可以在`config/telescope.php` 文件的 `ignore_abilities` 选项中指定它们: 'watchers' => [ Watchers\GateWatcher::class => [ 'enabled' => env('TELESCOPE_GATE_WATCHER', true), 'ignore_abilities' => ['viewNova'], ], ... ], ### 进程监听 进程监听器记录应用程序分派的任何作业的数据和状态。 ### 日志监听 日志监视器记录应用程序写入的任何日志的日志数据。 ### 邮件监听 邮件监视器允许您查看电子邮件的浏览器内预览及其相关数据。您也可以将该电子邮件下载为 `.eml` 文件。 ### 模型监听 只要调度了模型的 `create`、`updated`、`restored` 或 `deleted` 事件,模型观察器就会记录模型更改。您可以通过监听器的 `events` 选项指定应记录哪些模型事件: 'watchers' => [ Watchers\ModelWatcher::class => [ 'enabled' => env('TELESCOPE_MODEL_WATCHER', true), 'events' => ['eloquent.created*', 'eloquent.updated*'], ], ... ], ### 消息通知监听 消息通知监听器记录您的应用程序发送的所有通知。如果通知触发了电子邮件并且您启用了邮件监听器,则电子邮件也可以在邮件监视器屏幕上进行预览。 ### 数据查询监听 数据查询监听器记录应用程序执行的所有查询的原始 SQL、绑定和执行时间。观察者还将任何慢于 100 毫秒的查询标记为 `slow`。您可以使用观察者的 `slow` 选项自定义慢查询阈值: 'watchers' => [ Watchers\QueryWatcher::class => [ 'enabled' => env('TELESCOPE_QUERY_WATCHER', true), 'slow' => 50, ], ... ], ### Redis 监听 必须启用 Redis 事件才能使 Redis 监听器正常运行。您可以通过在 app/Providers/AppServiceProvider.php 文件的 boot 方法中调用 Redis::enableEvents() 来启用 Redis 事件。 Redis 监听器记录您的应用程序执行的所有 Redis 命令。如果您使用 Redis 进行缓存,Redis 监听器也会记录缓存命令。 ### 请求监听 请求监听器记录与应用程序处理的任何请求相关联的请求、标头、会话和响应数据。您可以通过 `size_limit` (以 KB 为单位)选项限制响应数据: 'watchers' => [ Watchers\RequestWatcher::class => [ 'enabled' => env('TELESCOPE_REQUEST_WATCHER', true), 'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64), ], ... ], ### Schedule 监听 Schedule 监听器记录应用程序运行的任何计划任务的命令和输出。