📚 课程目录第3章异常分类与排查思路

3. 异常分类与排查思路：常见异常类型及排查方法论

Iceberg 表在生产环境中出现异常时，表象往往千差万别：查询报错、数据“变少”、提交卡死、元数据膨胀……但绝大多数问题都可以归因到三类核心对象上：元数据（Metadata）、数据文件（Data Files）与快照（Snapshot）。理解这三者之间的关系，是建立排查思路的第一步。

3.1 三类核心异常的本质

Iceberg 的元数据层采用“版本化”设计，每次提交都会生成一个新的 metadata.json，并指向一个不可变的快照列表。数据文件则通过 Manifest 清单被快照引用。因此，异常的本质可以归纳为：引用断裂、状态不一致或生命周期失控。

异常大类	典型表现	根因方向	影响范围
元数据不一致	表无法加载、时间旅行失败、schema 错乱	多写者并发提交未正确合并；外部工具直接修改元数据；版本回退不当	表级可用性
数据文件丢失/损坏	查询报 FileNotFound、数据缺失、checksum 失败	外部清理任务误删文件；存储桶生命周期策略过期；部分写入未提交即被清理	分区/文件级
快照异常	快照数量激增、过期快照无法删除、孤立文件残留	频繁提交未触发快照过期；expire 与 orphan 清理未配合；时间线分叉	存储成本与性能

核心判断原则：先判断异常发生在“元数据读取阶段”还是“数据扫描阶段”。前者通常报错在计划阶段（如 MetadataNotFoundException），后者通常报错在执行阶段（如 FileNotFoundException）。这一区分能快速缩小排查范围。

3.2 排查方法论：分层递进法

面对 Iceberg 表异常，推荐采用“三层递进”的排查路径，避免在表象上打转：

第一层：元数据完整性检查 —— 确认表能否加载、当前元数据版本是否可读、历史版本是否完整。
第二层：快照与 Manifest 一致性检查 —— 确认快照引用的 Manifest 列表是否存在、Manifest 中声明的数据文件是否真实存在。
第三层：数据文件与存储底层核对 —— 确认文件在对象存储中的实际状态、大小、etag 与 Manifest 记录是否匹配。

每一层都有对应的“探针”工具和命令。例如，使用 org.apache.iceberg.util.PropertyUtil 或直接调用 IcebergTableOperations 的 refresh() 方法，可以快速感知元数据刷新失败的具体原因。

# 通过 Spark 读取 Iceberg 表元数据（第一层探针）
spark.sql("REFRESH TABLE db.tbl")
spark.sql("SELECT * FROM db.tbl.snapshots").show()

# 检查指定快照的 Manifest 列表（第二层探针）
spark.sql("SELECT * FROM db.tbl.manifests WHERE snapshot_id = 1234567890").show()

# 直接访问存储路径，核对文件是否存在（第三层探针）
hdfs dfs -ls /warehouse/db/tbl/data/partition_col=2024/

3.3 典型异常场景与排查路径

场景一：元数据不一致 —— “表突然读不了”

现象：应用报错 org.apache.iceberg.exceptions.ValidationException: Cannot commit, found new metadata，或查询时提示 Snapshot not found。

排查路径：

检查当前表元数据版本：SELECT * FROM db.tbl.metadata_log_entries 查看最近提交记录。
确认是否有多个写入任务并发提交，且未启用 iceberg.tbl.write.wap.enabled 或分支隔离。
查看是否有人为执行了 ALTER TABLE ... SET TBLPROPERTIES 修改了 format-version 或 commit.retry 参数。

常见误区：不要直接删除或回退 metadata.json 文件来“修复”问题。Iceberg 元数据是线性版本链，随意回退会导致后续快照全部失效，且可能造成数据文件被误判为孤立文件而被清理。

场景二：数据文件丢失 —— “查询报 FileNotFound”

现象：执行查询时抛出 java.io.FileNotFoundException，但表元数据加载正常。

排查路径：

定位报错文件路径，判断属于哪个分区、哪个快照。
查询该快照对应的 Manifest 列表，确认文件是否被正确引用。
检查存储侧的生命周期规则：是否配置了基于“最后访问时间”的自动清理？是否有人手动删除了 data/ 目录下的部分文件？

-- 找出引用丢失文件的快照与 Manifest
SELECT m.path, m.snapshot_id 
FROM db.tbl.manifests m 
WHERE m.path LIKE '%lost_file.parquet%';

-- 检查该文件是否被多个快照引用
SELECT s.snapshot_id, s.timestamp_ms 
FROM db.tbl.snapshots s 
WHERE s.snapshot_id IN (SELECT snapshot_id FROM db.tbl.manifests WHERE path LIKE '%lost_file.parquet%');

场景三：快照异常 —— “存储成本飙升”

现象：表目录下 metadata/ 文件数量超过数千个，或 data/ 目录下存在大量未被任何快照引用的孤立文件。

排查路径：

统计快照数量：SELECT count(*) FROM db.tbl.snapshots。
检查是否定期执行 expire_snapshots 和 remove_orphan_files。
确认写入频率与快照过期策略是否匹配：如果每 5 分钟提交一次，但快照保留策略为 7 天，则最多保留 2016 个快照，元数据压力极大。

建议：将快照过期与孤立文件清理纳入自动化运维脚本，并设置监控告警。例如，当 metadata/ 目录下文件数超过 500 时触发告警。

3.4 可视化：异常分类与排查决策树

下图展示了从“发现异常”到“定位根因”的完整决策路径，帮助运维人员快速判断当前异常属于哪一类别，并选择对应的处理手段。

3.5 排查误区与复盘要点

误区一：发现数据文件丢失就立刻从 HDFS 回收站恢复文件。Iceberg 的 Manifest 中记录了文件的精确路径和快照 ID，如果直接恢复文件但未恢复对应的元数据引用，查询依然会失败。正确做法是先确认该文件是否仍被某个有效快照引用，再决定恢复策略。

误区二：频繁执行 expire_snapshots 却不执行 remove_orphan_files。前者只清理元数据引用，后者才真正释放存储空间。两者必须配合使用，否则存储成本问题无法根治。

复盘建议：每次异常处理后，记录以下信息形成知识库：异常发生时间、表名、报错堆栈、根因分类（元数据/数据文件/快照）、修复动作、预防措施。建议使用 metadata_log_entries 中的历史记录辅助复盘，它能清晰展示每次提交前后的元数据变化。

总结而言，Iceberg 表异常排查的核心在于“分层定位、引用优先”。先确认元数据层是否完好，再检查快照与 Manifest 的引用链，最后核对存储底层的物理文件。通过这套方法论，绝大多数异常都能在 30 分钟内完成根因定位。