Laravel Telescope

简介

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

Brtb1DNyg7.png!large

安装

你可以使用 Composer 在 Laravel 项目中安装 Telescope 扩展:

  1. composer require laravel/telescope

安装 Telescope 后,可以在 Artisan 使用 telescope:install 命令来配置扩展实例。安装 Telescope 后,还应运行 migrate 命令:

  1. php artisan telescope:install
  2. php artisan migrate

更新 Telescope

更新 Telescope 时,您应该重新配置加载 Telescope 实例:

  1. php artisan telescope:publish

仅在特定环境中安装

如果您打算仅使用 Telescope 来协助您的本地开发。可以使用 —dev 标志安装 Telescope:

  1. composer require laravel/telescope --dev

运行 telescope:install 后,您应该从 app 配置文件中删除 TelescopeServiceProvider 服务提供注册。相反,在 AppServiceProviderregister 方法中手动注册服务:

  1. /**
  2. * 注册应用服务。
  3. *
  4. * @return void
  5. */
  6. public function register()
  7. {
  8. if ($this->app->isLocal()) {
  9. $this->app->register(TelescopeServiceProvider::class);
  10. }
  11. }

定制数据迁移

如果您不打算使用 Telescope 的默认迁移,则应该在 AppServiceProviderregister 方法中调用 Telescope::ignoreMigrations 方法。您可以使用 php artisan vendor:publish —tag=telescope-migrations命令导出默认迁移。

配置

使用 Telescope,其主要配置文件将位于 config/telescope.php。此配置文件允许您配置监听程序选项,每个配置选项都包含其用途说明,因此请务必彻底浏览此文件。

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

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

数据修改

有了数据修改,telescope_entries 表可以非常快速地累积记录。为了缓解这个问题,你应该使用 Artisan 每天运行 telescope:prune 命令:

  1. $schedule->command('telescope:prune')->daily();

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

  1. $schedule->command('telescope:prune --hours=48')->daily();

仪表板授权

Telescope 在 /telescope 处显示仪表板。默认情况下,您只能在 本地 环境中访问此仪表板。在你的 app/Providers/TelescopeServiceProvider.php 文件中,有一个 gate 方法。此授权能控制在 非本地 环境中对 Telescope 的访问。您可以根据需要随意修改此权限限制以对 Telescope 安装和访问:

  1. /**
  2. * 注册 Telescope gate.
  3. *
  4. * 使用 Gate 决定谁可以在非本地环境中访问 Telescope。
  5. *
  6. * @return void
  7. */
  8. protected function gate()
  9. {
  10. Gate::define('viewTelescope', function ($user) {
  11. return in_array($user->email, [
  12. 'taylor@laravel.com',
  13. ]);
  14. });
  15. }

过滤

单项过滤

您可以通过在 TelescopeServiceProvider 中注册的 filter 回调来过滤 Telescope 记录的数据。默认情况下,此回调会记录 本地 环境中的所有数据以及所有其他环境中的异常、进程中断、计划任务和带有受监控标记的数据:

  1. /**
  2. * 注册应用服务
  3. *
  4. * @return void
  5. */
  6. public function register()
  7. {
  8. $this->hideSensitiveRequestDetails();
  9. Telescope::filter(function (IncomingEntry $entry) {
  10. if ($this->app->isLocal()) {
  11. return true;
  12. }
  13. return $entry->isReportableException() ||
  14. $entry->isFailedJob() ||
  15. $entry->isScheduledTask() ||
  16. $entry->hasMonitoredTag();
  17. });
  18. }

批量过滤

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

  1. use Illuminate\Support\Collection;
  2. /**
  3. * 注册应用服务
  4. *
  5. * @return void
  6. */
  7. public function register()
  8. {
  9. $this->hideSensitiveRequestDetails();
  10. Telescope::filterBatch(function (Collection $entries) {
  11. if ($this->app->isLocal()) {
  12. return true;
  13. }
  14. return $entries->contains(function ($entry) {
  15. return $entry->isReportableException() ||
  16. $entry->isFailedJob() ||
  17. $entry->isScheduledTask() ||
  18. $entry->hasMonitoredTag();
  19. });
  20. });
  21. }

标签

Telescope 允许你通过 tag 搜索条目。通常,标签是 Eloquent 的模型类名或经过身份验证的用户id,这些标签会自动添加到条目中。有时,您可能希望将自己的自定义标签附加到条目中。你可以使用 telescope::tag 方法。 tag 方法接受一个回调,该回调应返回一个标签数组。回调返回的标签将与 telescope 自动附加到条目的任何标签合并。您应该在TelescopeServiceProvider 中调用tag方法:

  1. use Laravel\Telescope\Telescope;
  2. /**
  3. * 注册应用服务
  4. *
  5. * @return void
  6. */
  7. public function register()
  8. {
  9. $this->hideSensitiveRequestDetails();
  10. Telescope::tag(function (IncomingEntry $entry) {
  11. if ($entry->type === 'request') {
  12. return ['status:'.$entry->content['response_status']];
  13. }
  14. return [];
  15. });
  16. }

可用的监听

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

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

一些监听器还允许您提供其他自定义选项:

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

缓存监听

当缓存键被命中、遗漏、更新和遗忘时,缓存监听器会记录数据。

命令监听

只要执行 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. ],

数据监听

数据监听器在 Telescope 中记录并显示您的数据变量。使用 Laravel 时,可以使用全局 dump 函数输出变量。必须在浏览器中打开数据监听器选项卡,才能进行输出变量,否则监听器将忽略此次输出。

事件监听

事件监听器记录应用程序调度的任何事件的有效负载、监听器和广播数据。事件监听器忽略了 Laravel 框架的内部事件。

异常监听

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

Gate 监听

Gate 监听器记录您的应用程序的 Gate 和策略检查的数据和结果。如果您希望将某些能力排除在监听器的记录之外,您可以在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. ],

进程监听

进程监听器记录应用程序分派的任何作业的数据和状态。

日志监听

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

邮件监听

邮件监视器允许您查看电子邮件的浏览器内预览及其相关数据。您也可以将该电子邮件下载为 .eml 文件。

模型监听

只要调度了模型的 createupdatedrestoreddeleted 事件,模型观察器就会记录模型更改。您可以通过监听器的 events 选项指定应记录哪些模型事件:

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

消息通知监听

消息通知监听器记录您的应用程序发送的所有通知。如果通知触发了电子邮件并且您启用了邮件监听器,则电子邮件也可以在邮件监视器屏幕上进行预览。

数据查询监听

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

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

Redis 监听

必须启用 Redis 事件才能使 Redis 监听器正常运行。您可以通过在 app/Providers/AppServiceProvider.php 文件的 boot 方法中调用 Redis::enableEvents() 来启用 Redis 事件。

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

请求监听

请求监听器记录与应用程序处理的任何请求相关联的请求、标头、会话和响应数据。您可以通过 size_limit (以 KB 为单位)选项限制响应数据:

  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. ],

Schedule 监听

Schedule 监听器记录应用程序运行的任何计划任务的命令和输出。

本文章首发在 LearnKu.com 网站上。

本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接 我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。