📚 课程目录第3章故障分类与诊断方法

3. 故障分类与诊断方法：常见故障类型、诊断工具与日志分析

3.1 核心原理：Delta Lake 存储层故障的三层分类模型

Delta Lake 存储层故障并非随机出现，而是沿着其架构的层次结构逐层传导。理解故障分类，首先要建立“存储介质层 → 事务日志层 → 表语义层”的三层模型。底层故障会向上层表现为不同症状，而诊断时必须反向逐层下探。

存储介质层故障：对象存储（S3/OSS/ADLS）的临时性 5xx 错误、网络分区、凭证过期、桶策略误配置。典型特征是错误码直接来自云厂商 SDK，如 SlowDown、RequestTimeout。
事务日志层故障：_delta_log 目录下的 JSON 文件缺失、CRC 校验失败、版本序列断裂、并发写导致的提交冲突。典型特征是 Delta Lake 客户端抛出 DeltaConcurrentModificationException 或 CheckpointIOException。
表语义层故障：Schema 不匹配、分区列类型漂移、数据文件与日志中记录的 add 操作不一致、孤立文件（orphan files）堆积。典型特征是查询结果与预期不符，或 VACUUM 误删仍在使用的文件。

诊断原则：永远从“用户可感知的症状”（查询失败、写入超时、数据不一致）出发，先判断属于哪一层，再决定使用哪类工具。跨层直接排查往往浪费时间——例如，看到 FileNotFoundError 就认为是存储问题，实际可能是事务日志回滚不完整所致。

3.2 方法流程：故障诊断的五步定位法

面对 Delta Lake 存储层故障，推荐采用以下五步流程，每一步都有明确的输入、输出和判断标准。

症状捕获：记录完整异常堆栈、SQL 执行计划、任务重试次数。不要只保存错误摘要，必须保留 driver 和 executor 两侧的日志。
日志分层检索：按时间窗口在 Spark Driver 日志中搜索 Delta 关键字，在存储访问日志中搜索 REST API 调用记录。将两类日志按时间对齐。
事务日志体检：使用 delta-dump 工具或直接读取 _delta_log 目录，检查版本连续性、Checkpoint 有效性、最近 100 个提交的元数据。
文件引用校验：对比事务日志中的 add 操作与实际存储中的 Parquet 文件列表，找出“日志有但文件无”或“文件有但日志无”的差异项。
最小复现验证：构造一个只读取故障分区或故障文件的 DataFrame，确认问题是否可稳定复现，从而区分“瞬时故障”与“持久性损坏”。

关键命令速查：

# 查看事务日志版本序列（检查断裂）
ls -la /path/to/table/_delta_log/ | tail -20

# 使用 Delta Lake 自带工具导出元数据
spark-sql --packages io.delta:delta-core_2.12:2.4.0 \
  -e "DESCRIBE DETAIL delta.`s3://bucket/table`"

# 检查孤立文件（dry run）
VACUUM delta.`s3://bucket/table` RETAIN 168 HOURS DRY RUN

3.3 案例场景：并发写冲突与日志版本断裂的联合诊断

场景描述：某数据团队使用 Spark Structured Streaming 每小时写入 Delta 表，同时一个批处理任务每天凌晨 2 点执行 OPTIMIZE。某日发现批处理任务连续失败，错误信息为 DeltaConcurrentModificationException，但流式任务运行正常。

诊断过程：

步骤	操作	发现
1	查看批处理任务堆栈	失败于提交 `commit 4523`，版本冲突
2	检查 `_delta_log` 目录	发现 `4523.json` 存在但 `4522.json` 缺失
3	对比 Checkpoint 元数据	Checkpoint 最后版本为 4518，与 4523 相差 5 个版本
4	分析流式任务日志	流式任务在 4522 版本提交时发生网络抖动，导致日志文件未完整写入

根因：流式任务在写入 4522.json 时进程被 kill，文件只写了一半（CRC 校验失败）。批处理任务尝试基于 4521 版本提交，但 Delta Lake 检测到 4522 的临时文件存在，误判为并发冲突。

修复方案：

# 1. 备份损坏的日志文件
mv _delta_log/4522.json _delta_log/4522.json.corrupt

# 2. 使用 Delta Lake 的修复命令重建日志（需停止写入）
spark-sql --packages io.delta:delta-core_2.12:2.4.0 \
  -e "FSCK REPAIR TABLE delta.`s3://bucket/table`"

# 3. 验证版本连续性
ls _delta_log/*.json | wc -l   # 应等于最大版本号 + 1

重要提醒：切勿直接手动删除 _delta_log 中的 JSON 文件来“解决”冲突。必须先确认该版本是否已被 Checkpoint 覆盖，否则会导致数据文件成为孤立文件，后续 VACUUM 可能将其永久删除。

3.4 误区与复盘：诊断中的常见陷阱

在大量生产故障复盘中发现，以下三个误区最容易延长故障恢复时间：

误区一：只查 Spark 日志，忽略存储侧日志。Delta Lake 的很多故障根因在对象存储的访问日志中才能看到，例如 503 错误后的重试策略不当。建议同时开启云厂商的 CloudTrail 或 OSS Access Log。
误区二：将 Checkpoint 当作权威数据源。Checkpoint 是定期快照，默认每 10 个版本生成一次。如果故障发生在两个 Checkpoint 之间，仅靠 Checkpoint 无法定位问题，必须逐条解析 JSON 日志。
误区三：盲目执行 VACUUM 清理“垃圾”。在未确认事务日志完整性的情况下执行 VACUUM，可能删除仍被历史版本引用的数据文件。正确做法是先运行 DRY RUN，并检查输出文件列表是否包含活跃文件。

复盘建议：每次故障修复后，应保留完整的诊断时间线（从症状出现到根因确认的每一步操作及日志截图），并更新团队的故障知识库。对于 Delta Lake 这类事务性存储引擎，建议建立“事务日志版本连续性”的定期巡检任务，使用脚本每日检查 _delta_log 目录中是否存在版本号空洞或文件大小异常（正常 JSON 文件应大于 200 字节）。