pt-query-digest 是 Percona Toolkit 中的高级慢日志分析工具，支持 SQL 指纹归一化、执行时间建模、I/O 与锁等待拆解及 HTML 报告生成；而 mysqldumpslow 仅做基础正则分组，无法识别查询模板或揭示锁等待占比等关键问题。
pt-query-digest 是什么，为什么不能只用 mysqldumpslow
pt-query-digest 是 Percona Toolkit 中最核心的慢日志分析工具，它不是简单统计出现次数或排序耗时，而是对每条 SQL 做指纹归一化、执行时间分布建模、I/O 和锁等待拆解，并支持输出 HTML 报告、聚合指标、异常检测。而 mysqldumpslow 只做基础正则分组和计数，无法识别 WHERE user_id = 1 和 WHERE user_id = 999 属于同一条模板，更不会告诉你某类查询平均 Lock_time 占比高达 78%——这往往意味着事务未提交或间隙锁冲突。
安装与基础命令：必须加 --no-report 和 --review 参数
CentOS/RHEL 上安装（MySQL 5.7/8.0 兼容）：
yum install -y perl-DBI perl-DBD-MySQL perl-Time-HiRes perl-TermReadKey perl-IO-Socket-SSL
然后下载并安装 Percona Toolkit（推荐 3.5+ 版本）：
wget https://downloads.percona.com/downloads/percona-toolkit/3.5.4/binary/redhat/8/x86_64/percona-toolkit-3.5.4-1.el8.x86_64.rpm<br>rpm -ivh percona-toolkit-3.5.4-1.el8.x86_64.rpm
关键命令结构（不加 --no-report 会直接刷屏，掩盖真正问题）：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
-
pt-query-digest /var/log/mysql/slow.log --no-report --review h=localhost,D=test,t=slow_log_review：先将解析结果存入 MySQL 表，便于后续查重、打标、追踪 -
pt-query-digest /var/log/mysql/slow.log --limit 10 --report-format json：导出前 10 条的 JSON 结构，方便脚本消费 -
pt-query-digest /var/log/mysql/slow.log --since "2026-06-30 00:00:00" --until "2026-07-01 23:59:59"：按时间窗口切片，避免全量日志拖慢分析
报告里真正要盯死的 3 个字段
生成 HTML 报告后（pt-query-digest --output slow_report.html /var/log/mysql/slow.log），不要只看 “Query_time” 总和。重点交叉看：
-
Rows_examinedvsRows_sent：比值 > 1000 就说明索引没生效，哪怕Query_time只有 0.02s。例如Rows_examined=124800, Rows_sent=12→ 比值 ≈ 10400，大概率是WHERE条件没走索引 -
Lock_time占比：在报告 Summary 表里找 “Lock time as percentage of total time”。如果超过 20%，立刻检查对应 SQL 是否在长事务中、是否缺少FOR UPDATE显式锁、是否有未提交的BEGIN -
full_scan标记：报告每条 query 的 Attributes 列里，若含full_scan，代表该语句触发了全表扫描，不管数据量大小，都该加索引或改写
容易被忽略的兼容性陷阱
pt-query-digest 默认按 MySQL 5.6 日志格式解析，但 MySQL 8.0.23+ 开启了 log_slow_extra=1 后，日志会多出 Rows_affected、Tmp_tables、InnoDB_trx_id 等字段。如果不加 --version 8.0 参数，会导致解析失败或字段错位：
- 错误现象：
Cannot parse line ... missing Query_time - 正确用法：
pt-query-digest --version 8.0 /var/log/mysql/slow.log - 若日志同时混有 5.7 和 8.0 格式（如主从混合环境），建议先用
grep -v "InnoDB_trx_id" slow.log > clean.log过滤再分析
另外，log_output=TABLE 模式下生成的 mysql.slow_log 表不能直接喂给 pt-query-digest —— 它只接受文件或标准输入，必须先导出：SELECT * FROM mysql.slow_log INTO OUTFILE '/tmp/slow_from_table.log'，再处理。
