047. 优雅的应用调试工具——laravel/telescope (5.7 新扩展)

优雅的应用调试工具——laravel/telescope (5.7 新扩展)

Telescope 是一个非常优雅的调试助手,提供了非常丰富的 Debug 功能,给开发及调试带来了极大的方便,如果你一直使用 Clockwork 或者 Laravel Debugbar 进行项目的调试,那么现在又多了一个新的选择。不过目前看来扩展包应该只支持 Laravel 5.7 及以上的版本,这节课我们在一个 5.7 的项目中快速安装测试一下。

安装

目前扩展包要求 Laravel 的版本大于 ~5.7.7 所以可以使用 composer update 更新更新一下你的版本,我当前使用的 Laravel 是 5.7.12

$ composer require laravel/telescope --dev

file

注意关于调试的扩展包,都应该安装在开发环境,所以增加 --dev 参数,如果你希望这个包作用在生产环境,可以去掉 --dev

扩展包刚刚发布没多久,还是会存在一些小 Bug,遇到问题可以去项目 issue 中反馈,同时注意一下扩展包的升级。

执行扩展包的安装命令:

$ php artisan telescope:install
$ php artisan migrate

file

扩展包发布了一个 Provider 并自动注册在了 config/app.php 中,发布了配置文件以及一些资源。

如果以后需要对这个扩展包升级,需要重新发布上面这些资源文件,可以执行 php artisan vendor:publish --tag=telescope-assets --force

扩展包创建了三张表,用来存储所有的监控信息。

file

使用

访问

直接访问 package.test/telescope 就可以看到 Telescope 的界面了。

file

针对本地环境,也就是 APP_ENV=local 时,用户可以随便访问这个界面,但是当部署到一些线上测试环境的时候,这样当然就不安全了,所以 Telescope 要求有权限的用户才能访问,需要将逻辑定义在 TelescopeServiceProvider 的 gate 方法中。

先来完成登录注册的逻辑。

$ php artisan make:auth

接着修改一下 TelescopeServiceProvider

app/Providers/TelescopeServiceProvider.php

.
.
.
    protected function gate()
    {
        Gate::define('viewTelescope', function ($user) {
            return in_array($user->email, [
                'admin@gmail.com'
            ]);
        });
    }
.
.
.

可以根据用户的权限做一些反正,这里可以简单的制定特定的用户名才能访问,继续修改一下 APP_ENV 改成任意值,比如 staging,再次访问 package.test/telescope 就会看到 403 了,没有权限访问。

对于 APP_ENV 不要使用 testing 这个词,testing 专门指单元测试。

file

使用 admin@gmail.com 注册一个用户就可以正常访问了。

默认情况下 Telescope 只针对本地环境监听所有的信息,其他环境只是检测一些重要的数据,比如现在就需要修改一下 TelescopeServiceProvider 中的逻辑,希望 localstaging 环境都有效:

app/Providers/TelescopeServiceProvider.php

.
.
.
    public function register()
    {
        // Telescope::night();

        Telescope::filter(function (IncomingEntry $entry) {
            if ($this->app->environment('local', 'staging')) {
                return true;
            }
            .
            .
            .

查看请求

随便访问几个页面:

file

可以进入每个请求,查看详情:

file

每个请求的时间,状态,是谁请求的,headersessionresponseQureies 都非常的清晰。

查看异常,日志以及模型变动

所有的异常和日志都会被记录,可以直接在 Telescope 的界面中查看,同时接口也是可以调试的,例如我们添加一个测试的接口,添加一些日志,然后抛出异常:

routes/api.php

.
.
.
Route::get('foobar', function() {
    Log::info('info 日志');
    Log::error('error 日志');

    $user = App\User::first();
    $user->name = 'foobar';
    $user->save();

    abort('403', 'test Exception');
});

可以针对当前这个请求查看请求使用的日志,查询,模型变动,缓存等等信息。并且 N+1 问题或者是慢查询扩展包都会标记出来。

file

Telescope 还会记录下来模型的所有变化:

file

测试邮件

邮件同样可以通过 Telescope 进行调试,可以增加一些测试的代码,为了方便就直接发送文本内容了,建议大家还是使用 邮件类 来发送邮件。

routes/api.php

.
.
.
Route::get('foobar', function() {
    Log::info('info 日志');
    Log::error('error 日志');

    $user = App\User::first();
    $user->name = 'foobar';
    $user->save();

    Mail::raw('Text email', function($message) {
        $message->to('admin@gmail.com')->subject('Welcome!');
    });

    abort('403', 'test Exception');
});

还需要将 env 中 MAIL_DRIVER 修改为 log

file

再次请求一下接口,就可以看到邮件了,由于我们发送的是纯文本,所以没有样式。

调试 Dump

Dump 是经常使用的调试命令,Telescope 让 Dump 调试起来更加的方便,如果我们保持 package.test/telescope/dumps 打开,然后在任意地方添加 Dump 调试,Dump 不会打印出来,而是输出在当前这个页面中,跟 beyondcode/laravel-dump-server 一样,但是省去了手动开启。

routes/api.php

Route::get('foobar', function() {
   .
   .

    dump('test dump');

    abort('403', 'test Exception');
});

file

监控

如果我们将 Telescope 应用在生产环境,那么默认情况下只会记录:

  • 可报告的异常;
  • 失败的 Job;
  • 执行过的计划任务;
  • 被监控的标签。

所以并不是所有的请求都会被记录,但是最后这个监控标签就很有用了,先将 APP_ENV 修改为 production,你会的发现请求并不会被记录。

可以添加一些标签,告诉 Telescope 记录这些数据,例如我们登录用户对应的标签是 Auth:ID,也可以使用用户登录的邮箱,以及模型的名称加 ID,可以看一下 telescope_entries_tags 表中自动记录的标签。

file

这样再次访问某些页面,就会对数据进行记录了。

清理

最后 Telescope 还提供了数据清理的功能,如果所有的请求都记录,那么会产生大量的记录,有个配置 TELESCOPE_LIMIT 用来清理数据,同时还可以运行 php artisan telescope:prune 清理 24 小时之前的数据,可以配置一个计划任务。

代码版本控制

$ git add -A
$ git commit -m 'laravel/telescope'

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

上一篇 下一篇
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
《L05 电商实战》
从零开发一个电商项目,功能包括电商后台、商品 & SKU 管理、购物车、订单管理、支付宝支付、微信支付、订单退款流程、优惠券等
贡献者:2