pt-galera-log-explainer

对多份 Galera 日志进行过滤、聚合并汇总时间线，是梳理 Galera/PXC 集群日志的工具箱。

语法

pt-galera-log-explainer [--since=] [--until=] [-vv] [--merge-by-directory] [--pxc-operator] <command> <paths ...>

用法示例

本工具只解析 Galera/PXC 的日志文件，不连接 MySQL，命令里写的都是日志路径。把示例中的 *.log、具体路径与 RFC3339 时间换成你自己的即可。

场景：单节点全量时间线

一台节点出问题，先把它的错误日志完整时间线拉出来看状态变迁（启动、加入集群、SST 等）：

pt-galera-log-explainer list --all /var/log/mysql/*.log

场景：多节点日志合并看集群事件

集群整体抖动，需要把多个节点的日志按节点名/IP/uuid 对齐成一条时间线，定位是哪台先掉队：

pt-galera-log-explainer list --all \
  /var/log/mysql/node1.log \
  /var/log/mysql/node2.log \
  /var/log/mysql/node3.log

场景：只看 SST 与 view 变化

排查节点加入/掉线、SST 传输这类结构性事件，过滤掉一般报错噪声：

pt-galera-log-explainer list --sst --views /var/log/mysql/*.log

场景：按时间窗口缩小范围

已知故障发生在某个时段，用 --since/--until 把时间线掐头去尾，只盯那一窗口：

pt-galera-log-explainer list --all \
  --since 2023-01-05T03:24:26.000000Z \
  --until 2023-01-05T03:40:00Z \
  /var/log/mysql/*.log

场景：反查节点身份

日志里只看到一个 IP 或 uuid，想知道它对应哪个节点名，用 whois 反查：

pt-galera-log-explainer whois '172.17.0.3' /var/log/mysql/*.log

场景：列出复制冲突投票

Galera 4 集群出现写入冲突（如多节点同时改同一行），把每次复制失败的投票列出来查根因（输出 JSON 便于脚本处理）：

pt-galera-log-explainer conflicts --json /var/log/mysql/*.log

子命令

list —— 按时间线列出关键事件

pt-galera-log-explainer [flags] list { --all | [--states] [--views] [--events] [--sst] [--applicative] } <paths ...>

按时间顺序列出任意数量节点的关键事件（SST、view 变化、一般错误、维护操作）， 并通过节点名、IP 和 Galera 内部标识符把多份日志聚合在一起。

# 单节点
pt-galera-log-explainer list --all --since 2023-01-05T03:24:26.000000Z /var/log/mysql/*.log
# 多节点
pt-galera-log-explainer list --all *.log
# 按事件类型过滤
pt-galera-log-explainer list --sst --views *.log

whois —— 查询节点信息

用任意类型的线索（节点名 / IP / uuid）反查节点信息：

pt-galera-log-explainer [flags] whois [--json] [--type { nodename | ip | uuid | auto }] <information to search> <paths ...>

pt-galera-log-explainer whois '218469b2' mysql.log
pt-galera-log-explainer whois '172.17.0.3' mysql.log
pt-galera-log-explainer whois 'galera-node2' mysql.log

conflicts —— 列出复制冲突投票

列出所有复制失败的投票记录（Galera 4）：

pt-galera-log-explainer conflicts [--json|--yaml] *.log

ctx —— 输出单个日志的内部上下文

包含工具从该日志提取的一切：版本、SST 信息、uuid-ip-节点名映射等：

pt-galera-log-explainer ctx mysql.log

regex-list —— 列出全部内置正则

打印工具使用的所有正则（regex、用于提取信息的 internalRegex、所属 type、 输出所需的 verbosity 级别）：

pt-galera-log-explainer regex-list

选项

选项	说明
--config	逗号分隔的配置文件列表（不带等号），必须是第一个选项；缺省时使用默认位置
-h, --help	显示帮助并退出
--no-color	去掉所有颜色转义字符
--since	只列出该日期之后的事件（会影响应用于日志的正则）。格式：2023-01-23T03:53:40Z（RFC3339）
--until	只列出该日期之前的事件（仅在工具循环中生效，不改变正则）。格式同上
--merge-by-directory	不依赖提取的信息，而按日志所在的基础目录合并；日志稀疏且已按节点分目录时有用
--skip-merge	禁用日志合并；所有节点的 wsrep_node_name 相同时可用
-v, --verbosity	-v：在时间线中显示工具使用的全部 mysql 信息；-vv：工具内部调试
--pxc-operator	分析来自 Percona PXC operator 的日志：防止日志被合并、增加 operator 专属正则、并为 pt-k8s-debug-collector 抓取的日志微调正则。默认关闭（对非 k8s 环境有性能影响）
--skip-operator-detection	禁用 PXC operator 日志的自动检测
--exclude-regexes	从分析中移除指定正则（列表可用 `regex-list
--grep-cmd	grep v3 可执行文件路径；Darwin 系统可能需设为 ggrep。默认 grep
--custom-regexes	添加自定义正则（以洋红色打印）。格式：(golang regex string)=[可选的静态提示信息]，多条用分号分隔；静态信息为空时打印捕获的字符串
--version	显示版本并退出

系统要求与兼容性

• 需要 grep v3；macOS 自带 grep 为 v2，需通过 --grep-cmd 指向 ggrep。
• 兼容 Percona XtraDB Cluster 5.5–8.0、MariaDB Galera Cluster 10.0–10.6， 以及 PXC operator pod 日志（error.log、recovery.log、post.processing.log）。

已知问题

• 不支持共享同一 IP 或节点名相同的节点。
• 稀疏日志的文件识别可能失败，导致显示很多列；可用 --merge-by-directory（要求文件已按目录组织）。
• 某些信息可能缺失：可能是尚未实现，或因不可靠而被禁用（如节点索引号）。
• 列宽有时过大（通常是打印带长节点名的 SST 事件时）。
• 个别显示问题（事件未去重等）源于隐藏的内部事件。

其他信息

• 作者：Yoann La Cancellera

• 通用说明：已知问题的反馈方式、PTDEBUG 调试安全提示、系统要求基线，见 通用说明。

更多细节请阅读 官方文档。