CephFS 日志急救指南:cephfs-journal-tool 全面剖析与实战
CephFS 日志急救指南:cephfs-journal-tool 全面剖析与实战
当 CephFS 的元数据日志(mdlog)因异常断电、对象丢失或人为误操作而损坏时,文件系统可能无法正常挂载或启动。cephfs-journal-tool 正是 Ceph 为这类场景提供的专家级离线诊断与修复工具:它允许管理员在文件系统非活跃状态下检查日志健康度、备份与回灌日志、修改日志头指针、检索或清除日志事件,甚至从日志中恢复目录项(dentry)。读完本文,你将掌握 cephfs-journal-tool 的三种操作模式(journal、header、event)、全部子命令与过滤器的用法,并理解其背后基于 JournalScanner、Dumper、Resetter 等组件的实现原理。
⚠️ 使用前务必阅读:该工具会直接修改文件系统的内部数据结构(RADOS 中的日志对象与元数据对象)。请在操作前做好备份、逐条核对命令,并在不确定时寻求专家意见。作为额外保护,
cephfs-journal-tool无法在活跃(active)文件系统上运行——源码 src/tools/cephfs/JournalTool.cc 会检查对应 rank 是否处于 active 状态并直接返回-EPERM。
语法总览:三种操作模式
工具整体语法如下(摘自 doc/cephfs/cephfs-journal-tool.rst 与工具自带 usage,见 src/tools/cephfs/JournalTool.cc):
cephfs-journal-tool [options] journal <inspect|import|export|reset>
cephfs-journal-tool [options] header <get|set> <trimmed_pos|expire_pos|write_pos|pool_id> <value>
cephfs-journal-tool [options] header recover [--force]
cephfs-journal-tool [options] event <get|splice|recover_dentries> [filter] <list|json|summary|binary>
三种模式分别作用于三个不同粒度的对象:
journal模式:整个日志(journal),用于健康检查、整体备份与重置;header模式:日志头(header),用于查看与修正头指针字段;event模式:日志内部的事件(event),用于细粒度查看、筛选、删除与数据恢复。
在执行流程上,工具通过 JournalTool::main() 依次解析 --rank(必填)与 --journal(默认 mdlog)参数,建立与 RADOS 的连接后,将剩余参数分派到 main_journal / main_header / main_event 三个处理函数。--rank 支持 filesystem:{mds-rank|all} 形式,指定 all 时工具会对所有 rank 逐一执行(journal import 除外,见 can_execute_for_all_ranks,src/tools/cephfs/JournalTool.cc)。
Journal 模式:从整体评估日志健康
journal 模式是诊断工作的起点,用于评估整个日志的状态。
inspect:报告日志健康度,识别缺失的对象(missing objects)与损坏区域(corrupt regions)。需要注意:它只能确认“事件存在且可解码”,无法识别事件内部的不一致。export <file>/import <file>:以稀疏文件(sparse file)格式读写日志的二进制转储。import会校验导入日志的 FSID 与在线集群 FSID 是否一致,--force可跳过该校验;export对损坏日志(缺失对象)可能不可靠。reset:截断日志,丢弃其中所有信息。--force表示直接硬重置(hard reset),不再尝试从磁盘恢复。源码中reset命令还强制要求追加--yes-i-really-really-mean-it参数才会真正执行(见 JournalTool::main_journal),这是第二重保护。
示例:journal inspect
# cephfs-journal-tool journal inspect
Overall journal integrity: DAMAGED
Objects missing:
0x1
Corrupt regions:
0x400000-ffffffffffffffff
上述输出表示日志对象 0x1 缺失,且 0x400000 之后的区域无法解码。inspect 的实现位于 JournalTool::journal_inspect(),它创建 JournalScanner 扫描对象并调用 js.report() 输出报告。
示例:journal export / import
# cephfs-journal-tool journal export myjournal.bin
journal is 4194304~80643
read 80643 bytes at offset 4194304
wrote 80643 bytes at offset 4194304 to myjournal.bin
NOTE: this is a _sparse_ file; you can
$ tar cSzf myjournal.bin.tgz myjournal.bin
to efficiently compress it while preserving sparseness.
# cephfs-journal-tool journal import myjournal.bin
undump myjournal.bin
start 4194304 len 80643
writing header 200.00000000
writing 4194304~80643
done.
💡 最佳实践:在任何进一步操作之前,先执行
journal export <backup file>备份日志。借助稀疏文件特性,可用tar cSzf压缩备份而保持稀疏性。
export 会先扫描日志并确认头部有效、无对象缺失(js.is_readable()),否则建议改用 rados CLI 逐个对象导出(见 JournalTool::journal_export())。
源码视角:reset 做了什么
journal reset 通过 Resetter 组件完成:硬重置(--force)直接调用 resetter.reset_hard(),普通重置则调用 resetter.reset()(JournalTool::journal_reset())。与“清空”的直觉不同,reset 实际上是截断日志并插入一条 EResetJournal 事件,保证后续 MDS 重放(replay)时知道日志边界已被重置。
Header 模式:查看与修复日志头指针
日志头(journal header)记录了一组关键指针,CephFS 依靠它们定位日志的读写位置。header 模式提供三种操作:
get:输出当前日志头的全部内容(JSON 格式)。set <field> <value>:修改头字段。允许的字段为trimmed_pos、expire_pos、write_pos和pool_id。从源码看,字段被直接映射到Journaler::Header的成员:trimmed_pos、expire_pos、write_pos直接写入,而pool_id写入layout.pool_id(见 JournalTool::main_header())。recover:恢复mdlog中损坏的日志指针。它枚举日志事件并计算安全回退偏移:trimmed_pos:设置为日志段中发现的第一个事件的位置;expire_pos:设置为第一个 major segment 事件的位置;read_pos:设置为第一个 major segment 事件的位置;write_pos:设置为最后一个有效事件之后紧邻的位置。
示例:header get / set / recover
# cephfs-journal-tool header get
{ "magic": "ceph fs volume v011",
"write_pos": 4274947,
"expire_pos": 4194304,
"trimmed_pos": 4194303,
"stream_format": 1,
"layout": { "stripe_unit": 4194304,
"stripe_count": 1,
"object_size": 4194304,
"pool_id": 2,
"pool_ns": ""}}
# cephfs-journal-tool header set trimmed_pos 4194303
Updating trimmed_pos 0x400000 -> 0x3fffff
Successfully updated header.
# cephfs-journal-tool --rank a:0 header recover
Proposed Journal Header Updates:
trimmed_pos: 0x400000 -> 0x400000
expire_pos: 0x415f74 -> 0x415f74
read_pos: 0x415f74 -> 0x415f74
write_pos: 0x41576c -> 0x41676c
Target event type at proposed read_pos: EVENT_SUBTREEMAP
Dry-run mode enabled. Header modifications skipped.
# cephfs-journal-tool --rank a:0 header recover --force
Proposed Journal Header Updates:
trimmed_pos: 0x400000 -> 0x400000
expire_pos: 0x415f74 -> 0x415f74
read_pos: 0x415f74 -> 0x415f74
write_pos: 0x41576c -> 0x41676c
Target event type at proposed read_pos: EVENT_SUBTREEMAP
Successfully recovered journal header.
注意 header get 中 magic 字段 "ceph fs volume v011" 是日志格式标识;layout 中 object_size 为 4MB(4194304),这也是日志对象的分段大小。
header recover 的适用边界与执行逻辑
从文档与源码可以归纳出 header recover 的三个关键约束:
- 信任前提:它假定日志起始指针(
expire_pos)是合理的,并以此锚点确定扫描起点,再重新计算其余边界指针。因此,管理员在运行前应手动检查日志头,确认该指针在逻辑上说得通。 - 灾难场景不适用:当头对象完全丢失、或起始指针已不可修复地损坏时,本命令无法恢复未提交的元数据。
- 硬性要求:命令要求日志头存在且 magic 合法。若头缺失或完全无法识别(magic 不匹配
CEPH_FS_ONDISK_MAGIC),工具会直接中止。
实现上,JournalTool::recover_header() 通过流式扫描回调遍历全部日志事件,记录第一个事件位置、最后一个事件位置及其原始长度,并寻找最早出现的 major segment 边界事件(EVENT_SUBTREEMAP、EVENT_SUBTREEMAP_TEST、EVENT_LID、EVENT_RESETJOURNAL 之一)。扫描过程中若发现偏移不连续(gap),会打印 warning 并跳过继续。最终:
- 默认(不带
--force)为 dry run:只把 "Proposed Journal Header Updates" 打印到控制台,不落盘; - 仅当显式传入
--force时,才将更新后的头对象写回 RADOS(output.write_full(js.obj_name(0), header_bl))。
Event 模式:细粒度检索与数据恢复
Event 模式允许对日志内容进行详细检查与操作,可作用于日志中的全部事件,也可通过过滤器缩小范围:
cephfs-journal-tool event <action> [filter] <output>
动作(Actions)
get:从日志中读取事件;splice:擦除日志中的事件或区域(用ENoOp事件填充覆盖,见 JournalTool::erase_region());recover_dentries:从日志中恢复目录项。它执行一种选择性的离线重放:只读取日志中的 dentry,并且仅当其版本号大于底层存储(backing store)中的当前版本时才写回。源码 JournalTool::recover_dentries() 展示了完整的版本比较逻辑:对 fullbit / remotebit 逐项对比fb.inode->version与底层存储版本;对硬链接位(L/l)则退化为比较所在 dirfrag 的 fnode 版本;必要时还会重建缺失的 dirfrag 对象、创建缺失的 root inode,并在恢复完成后通过 consume_inos() 更新各 MDS 的 InoTable,防止已用 inode 号被再次分配。
过滤器(Filters)
过滤器可组合使用,语义为 AND(取各过滤器命中事件的交集):
| 过滤器 | 含义 |
|---|---|
--range <int begin>..[int end] |
只包含 begin(含)到 end(不含)范围内的事件 |
--path <path substring> |
只包含元数据路径中含指定字符串的事件 |
--inode <int> |
只包含元数据中含指定 inode 的事件 |
--type <type string> |
只包含指定类型的事件 |
--frag <ino>[.frag id] |
只包含涉及该目录分片(directory fragment)的事件 |
--dname <string> |
只包含目录分片内指定名称的 dentry 事件(必须与 --frag 联用) |
--client <int> |
只包含来自指定客户端会话 ID 的事件 |
--max-rss <bytes> |
(目前仅 recover_dentries 支持)按批次扫描并冲刷日志事件,限制工具的 RSS |
其中 --max-rss 的实现细节值得关注:源码在 JournalTool::main_event() 中将用户指定的字节数除以 3(因为“一个解码后的事件约占其编码流的 3 倍”),得到批次大小,随后通过回调在累积到 EVENT_SUBTREEMAP / EVENT_SUBTREEMAP_TEST 事件且字节数达标时触发批量冲刷(flush),从而把峰值内存控制在设定范围内。
输出模式(Output modes)
binary:将每个事件写为独立的二进制文件,放在由--path指定的目录中(文件命名形如0x<offset>_<TYPE>.bin,见 EventOutput::binary());json:把所有事件作为一个 JSON 序列化的对象列表,写入--path指定的单个文件(EventOutput::json());summary:在 stdout 输出人类可读的事件汇总(按类型统计计数);list:在 stdout 输出每种事件的类型及受影响的文件路径的简明清单。
示例:event 模式
# cephfs-journal-tool event get json --path output.json
Wrote output to JSON file 'output.json'
# cephfs-journal-tool event get summary
Events by type:
NOOP: 2
OPEN: 2
SESSION: 2
SUBTREEMAP: 1
UPDATE: 43
# cephfs-journal-tool event get list
0x400000 SUBTREEMAP: ()
0x400308 SESSION: ()
0x4003de UPDATE: (setattr)
/
0x40068b UPDATE: (mkdir)
diralpha
0x400d1b UPDATE: (mkdir)
diralpha/filealpha1
0x401666 UPDATE: (unlink_local)
stray0/10000000001
diralpha/filealpha1
0x40228d UPDATE: (unlink_local)
diralpha
stray0/10000000000
0x402bf9 UPDATE: (scatter_writebehind)
stray0
0x403150 UPDATE: (mkdir)
dirbravo
0x4037e0 UPDATE: (openc)
dirbravo/.filebravo1.swp
0x404032 UPDATE: (openc)
dirbravo/.filebravo1.swpx
# cephfs-journal-tool event get --path filebravo1 list
0x40785a UPDATE: (openc)
dirbravo/filebravo1
0x4103ee UPDATE: (cap update)
dirbravo/filebravo1
# cephfs-journal-tool event splice --range 0x40f754..0x410bf1 summary
Events by type:
OPEN: 1
UPDATE: 2
# cephfs-journal-tool event recover_dentries summary
Events by type:
LID: 1
SUBTREEMAP: 1
Errors: 0
# cephfs-journal-tool event get --inode=1099511627776 list
0x40068b UPDATE: (mkdir)
diralpha
0x400d1b UPDATE: (mkdir)
diralpha/filealpha1
0x401666 UPDATE: (unlink_local)
stray0/10000000001
diralpha/filealpha1
0x40228d UPDATE: (unlink_local)
diralpha
stray0/10000000000
# cephfs-journal-tool event get --frag=1099511627776 --dname=filealpha1 list
0x400d1b UPDATE: (mkdir)
diralpha/filealpha1
0x401666 UPDATE: (unlink_local)
stray0/10000000001
diralpha/filealpha1
# cephfs-journal-tool event get binary --path bin_events
Wrote output to binary files in directory 'bin_events'
从 list 输出可以看到 list 模式会同时打印事件偏移(如 0x4003de)、事件类型(如 UPDATE)、子操作(如 mkdir、unlink_local、openc)以及受影响的路径,其中路径前的偏移与 --range 过滤器使用的偏移是同一套坐标,便于交叉定位。
补充说明:recover_dentries 支持 --dry_run 参数(仅 mdlog 类型可用,见 JournalTool::main_event()),用于在不写 RADOS 的前提下预演恢复过程。若恢复目标元数据池与当前文件系统池不同,还可使用 --alternate-pool <name> 指定备选元数据池(JournalTool::main_event())。
通用选项与特殊选项
| 选项 | 说明 |
|---|---|
--rank=<filesystem>:{mds-rank|all} |
指定文件系统、MDS rank 或全部 rank(必填) |
--journal=<mdlog|purge_queue> |
日志类型,默认 mdlog;只有 mdlog 支持 event 模式。使用 purge_queue 时,日志扫描器会创建 PurgeItem 对象并加入 EventMap 处理 |
--alternate-pool <name> |
使用 recover_dentries 时指向备选元数据池 |
--max-rss <bytes> |
recover_dentries 事件恢复时每批允许的最大 RSS |
关于 purge_queue:JournalScanner::set_journal_ino()(src/tools/cephfs/JournalScanner.cc)会根据类型解析日志 inode——purge_queue 对应 MDS_INO_PURGE_QUEUE + rank,而 mdlog 则需先读取日志指针对象(MDS_INO_LOG_POINTER_OFFSET + rank)来定位实际日志头(JournalScanner::scan_pointer())。这解释了为什么 mdlog 扫描失败时常见报错是 "Pointer ... is absent / unreadable / corrupt"。
实战建议与验证
- 先备份,再动手:任何修改前先
cephfs-journal-tool journal export <file>;reset前务必确认--yes-i-really-really-mean-it的含义。 - 诊断顺序:
journal inspect评估整体健康 →header get人工核对指针合理性 → 视情况header recover(先 dry run 看提案,再--force落盘)→ 需要细粒度操作时再进入event模式。 - 测试验证:仓库自带冒烟测试 qa/workunits/suites/cephfs_journal_tool_smoke.sh 覆盖了 export/import 往返一致性、
journal reset、header set、event get summary/json/binary、event recover_dentries、event splice以及header recover(dry-run 与--force)的完整链路,可作为理解工具行为的参考范例。测试脚本还揭示了一个关键运维细节:recover_dentries会修改元数据对象(尤其是 InoTable),导致日志与元数据不再一致,因此测试在恢复目录项后执行journal reset与cephfs-table-tool all reset session使集群回到一致状态——真实故障恢复时也应参考这一顺序。 - 保持只读心态:
header set、event splice、journal reset都是破坏性操作,务必先在测试集群上演练;对不确定的场景优先使用 dry-run 类路径(如header recover默认行为、event recover_dentries --dry_run)。
相关源码路径速查
- 工具主实现:src/tools/cephfs/JournalTool.cc
- 工具头文件:src/tools/cephfs/JournalTool.h
- 日志扫描器:src/tools/cephfs/JournalScanner.cc
- 事件输出:src/tools/cephfs/EventOutput.cc
- 过滤器实现:src/tools/cephfs/JournalFilter.cc
- 日志导出/导入(Dumper):src/tools/cephfs/Dumper.cc
- 日志重置(Resetter):src/tools/cephfs/Resetter.cc
- 冒烟测试:qa/workunits/suites/cephfs_journal_tool_smoke.sh