SuperAPI AI 工具集

telescope-debugging

编程与开发

查看项目

更新于 11-06 21:03

技能介绍

该技能围绕两个 Artisan 命令展开,用于从终端读取 Telescope 记录的数据:telescope:list 用于查找条目,telescope:show 用于展示某个条目的完整批次信息。Telescope 将每个请求、任务和命令记录为一个批次(batch),批次中包含条目本身以及它产生的全部查询、缓存操作、日志、事件、异常和视图。

【使用流程】

  1. 查找条目:运行 php artisan telescope:list request(或 exception、job、query、cache),依据 URI、类名或耗时选择目标行,并复制其 UUID。若要看最近一条条目,可跳过此步。
  2. 展示批次:运行 php artisan telescope:show <uuid>,或 php artisan telescope:show latest:request。输出包含条目自身详情,以及来自同一批次的 Queries、Exceptions、Cache 和 Logs 各分区。
  3. 依据标记诊断:在 Queries 表中,DUP 标记 SQL 模式相同的查询,通常表示 N+1 问题;Source 列显示执行该查询的文件与行号(缩短为 basename,使用 --json 可获完整路径);SLOW 标记超过配置阈值的查询;Cache 标题显示命中、未命中与命中率;异常条目显示消息、代码上下文和堆栈跟踪。诊断完成的标准是定位到具体文件与行号或具体查询,而不仅仅是描述症状。

【JSON 输出】 两个命令均支持 --json。当需要精确值、过滤结果或输出较长时,优先使用该选项。telescope:list --json 输出条目数组;telescope:show --json 输出 {"entry": {...}, "batch": [...]},其中 batch 数组按时间顺序排列,并已按 --type 过滤。无匹配条目时,telescope:list --json 输出 [] 而非提示信息。每个条目包含 id、batch_id、type、content、family_hash 和 created_at;content 的键与对应类型的 Telescope UI 一致,例如 query 包含 sql、time、slow、file、line,exception 包含 class、message、file、line、trace。注意:tags 字段始终为 [](应使用 --tag 过滤而不是读取输出中的 tags),按 UUID 寻址时 sequence 为 null。

【示例(保留原文代码)】

Exception class, message, and location for the latest exception

php artisan telescope:show latest:exception --json | jq '.entry.content | {class, message, file, line}'

Slow queries in the latest request, with the file that ran them

php artisan telescope:show latest:request --json --type=query | jq '.batch[] | select(.content.slow) | {sql: .content.sql, time: .content.time, file: .content.file, line: .content.line}'

Repeated SQL patterns in a request (N+1 candidates), most repeated first

php artisan telescope:show latest:request --json --type=query | jq '[.batch[].content.sql] | group_by(.) | map({sql: .[0], count: length}) | sort_by(-.count) | .[] | select(.count > 1)'

Recent 500 responses

php artisan telescope:list request --json --limit=50 | jq '.[] | select(.content.response_status >= 500) | {id, uri: .content.uri, status: .content.response_status}'

Failed jobs and their exception messages

php artisan telescope:list job --json | jq '.[] | select(.content.status == "failed") | {id, name: .content.name, error: .content.exception.message}'

【参考选项】 latest 和 latest:{type} 无需 UUID 即可解析为最近一条条目,任何条目类型均可用,包括 latest:query 和 latest:job。任一命令上的 --json 会禁用截断,因此 --full 仅在表格输出时需要。telescope:show <id> --full 禁用 SQL、消息和载荷的截断。当请求产生数百条条目时,telescope:show <id> --type=query,exception 可将批次上下文限制为这些类型。telescope:list --tag=Auth:42 过滤某个已认证用户的条目,因为 Telescope 会以 Auth:<user id> 打标签。--batch=<id> 列出某个请求的全部条目。--before=<sequence> 使用页脚打印的游标向后分页。--family=<hash> 对同一异常的重复出现进行分组,hash 可从 --json 输出的 family_hash 字段读取。

运行任一命令时加 --help 可查看完整选项列表和有效条目类型。

【适用场景与限制】 适用于使用 Laravel Telescope 的应用在开发或排查阶段定位慢页面、异常、500 响应、失败任务及 N+1 查询等问题。资料未说明该技能是否适用于生产环境或特定 Laravel 版本,未提供超出上述内容的额外收费、平台或效果信息。