pt-query-digest 是什么
pt-query-digest 属于 Percona Toolkit，把慢日志按语句指纹聚合，输出按总响应时间排序的报告，包含执行次数、响应时间分布、扫描行数与样例 SQL。它解决的是「慢日志太长看不过来」的问题：先看总耗时占比最高的几组，再逐条优化，效率远高于人工翻日志。
基本信息
| 所属工具 | Percona Toolkit |
|---|---|
| 默认排序 | 按总响应时间（Response time） |
| 核心指标 | Calls、Rows examine、Query time 与响应时间分布 |
| 输入来源 | 慢日志文件，或 log_output=TABLE 时的 mysql.slow_log |
| 常用选项 | --limit / --sample / --filter / --since / --until |
典型使用场景
- 慢 SQL 治理：从占比最高的语句开始优化
- 定期报告：每周聚合对比，跟踪语句变化趋势
- 上线前后对比：确认新功能没有引入新的慢查询
- 时段排查：用 --since 与 --until 只看故障时间段
- 批量筛选：用 --filter 按库表或语句特征过滤
- 结果归档：把报告落库，形成可追溯的优化记录
- 实时表分析：直接分析 mysql.slow_log 表而不导出文件
常用用法
常用用法
# 分析文件，输出报告
pt-query-digest /var/log/mysql/slow.log > /tmp/slow_report.txt
# 只看总耗时前 5 组，每组附 3 条样例
pt-query-digest --limit 5 --sample 3 /var/log/mysql/slow.log
# 只分析某个时间段
pt-query-digest --since '2026-10-12 09:00:00' --until '2026-10-12 10:00:00' \
/var/log/mysql/slow.log
# 从实时表分析（log_output=TABLE）
pt-query-digest --type slowlog h=localhost,D=mysql,t=slow_log
# 只统计指定库的语句
pt-query-digest --filter '$event->{db} eq "appdb"' /var/log/mysql/slow.log报告字段读法
| 字段 | 含义 | 关注点 |
|---|---|---|
| Response time | 该组语句的总耗时与占比 | 占比高的先优化，收益最大 |
| Calls | 执行次数 | 次数与耗时都高说明是高频热点 |
| R/Call | 单次平均耗时 | 平均值高说明单条语句本身慢 |
| Rows examine | 平均扫描行数 | 远大于返回行数说明索引不理想 |
| Query_time distribution | 耗时分布直方图 | 长尾明显说明参数或数据分布差异大 |
| 样例 SQL | 该指纹下有代表性的语句 | 用于确认语句形态与实际表 |
报告头部「Profile」先看总耗时占比前几组：通常前 3 组就占了 60% 以上的时间。
语句指纹会把具体参数替换为占位符来聚合，所以「调用次数」只有聚合后才具备统计意义；要定位真实参数还得结合样例 SQL 与业务日志。