laravel telescope 提供开箱即用的实时调试监控仪表板，支持安装配置、查询日志分析、cli 检索及自定义扩展；需通过 composer 安装、迁移数据库、配置采集范围，并可在 web 界面或命令行查看慢查询、调用栈及导出日志。
如果您在开发 Laravel 应用时需要实时监控请求、数据库查询、异常、缓存操作等调试信息，但缺乏可视化工具支持，则 Laravel Telescope 提供了开箱即用的仪表板与日志分析能力。以下是使用 Telescope 进行查询日志分析的具体操作步骤：
一、安装与启用 Telescope
Telescope 是一个独立的 Laravel 包，需通过 Composer 安装并完成服务提供者注册与迁移，才能启用其日志收集与 Web 界面功能。
1、在项目根目录执行命令安装包：composer require laravel/telescope --dev。
2、运行 Artisan 命令发布资源与配置：php artisan telescope:install。
3、执行数据库迁移以创建 telemetry 表：php artisan migrate。
4、在 config/app.php 的 providers 数组中确认已注册 Laravel\Telescope\TelescopeServiceProvider::class（Laravel 8+ 默认自动发现，可跳过）。
二、配置 Telescope 数据采集范围
默认情况下 Telescope 会记录所有请求和查询，但生产环境需限制采集以保障性能；通过修改 config/telescope.php 可精细控制监听项与条件。
1、打开配置文件，定位到 'watchers' 数组，将不需要的日志类型设为 false，例如禁用 Redis 监控：'redis' => false。
2、在 'ignore_paths' 中添加无需监控的路由前缀，如：['/telescope', '/storage', '/vendor']。
3、设置查询慢日志阈值：在 'watchers' => ['queries' => [...]] 内添加 'slow' => 100，单位为毫秒，仅记录执行超 100ms 的 SQL。
三、查看数据库查询日志详情
Telescope 将每次 HTTP 请求关联的所有查询整合为一条入口记录，点击后可展开完整 SQL、绑定参数、执行时间及调用栈，便于定位 N+1 或冗余查询。
1、启动本地服务：php artisan serve，访问 http://127.0.0.1:8000/telescope 进入仪表板。
2、在顶部筛选栏选择 Requests 标签，找到目标请求条目并点击进入详情页。
3、向下滚动至 Queries 区域，每条 SQL 左侧显示执行耗时（绿色为快，红色为慢），点击右侧 View 可查看原始语句与参数绑定值。
4、若发现重复查询，点击对应条目右上角 Trace 查看 PHP 调用路径，快速定位模型关系加载或循环内查询问题。
四、使用 Telescope CLI 快速检索历史查询
Telescope 提供 Artisan 命令行接口，可在不打开浏览器的情况下按条件导出或过滤查询日志，适合 CI 环境或脚本化分析。
1、列出最近 10 条慢查询：php artisan telescope:prune --hours=1 --type=queries --slow=200。
2、导出某次请求 ID 的全部查询为 JSON：php artisan telescope:export --id=abc123 --type=queries > queries.json。
3、清除超过 24 小时的非错误类日志（保留 exceptions 和 failed_jobs）：php artisan telescope:prune --hours=24 --except=exceptions,failed_jobs。
五、自定义查询日志扩展分析字段
原生 Telescope 不记录查询影响行数、索引使用情况等 DB 层指标，可通过监听 Illuminate\Database\Events\QueryExecuted 事件注入额外元数据。
1、在 app/Providers/EventServiceProvider.php 的 $listen 数组中添加：'Illuminate\Database\Events\QueryExecuted' => [App\Listeners\LogQueryExtraInfo::class]。
2、运行 php artisan make:listener LogQueryExtraInfo 创建监听器，在 handle() 方法中调用 $event->connection->getPdo()->getAttribute(PDO::ATTR_SERVER_VERSION) 获取 MySQL 版本，并写入 $event->sql 关联的 Telescope 记录扩展字段。
3、重写 Telescope::recordQuery() 方法，在 app/Providers/AppServiceProvider.php 的 boot() 中调用 Telescope::filter() 注入自定义字段键名如 'affected_rows' 与 'using_index'。
