ScyllaDB Commit Log REST API 完全指南段文件管理、恢复与监控指标【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb导读Commit Log提交日志是 ScyllaDB 保障写入不丢失的核心机制所有写入操作在进入内存 Memtable 的同时也会被追加记录到磁盘上的 commit log 段文件中一旦节点崩溃或意外断电重启后即可通过重放 commit log 将尚未落盘的数据恢复到 Memtable。本文以仓库中 docs/reference/api/commit-log.rst 所描述的 REST API 为骨架结合 commitlog.json 接口定义、api/commitlog.cc 路由实现与 db/commitlog/commitlog.hh 底层源码系统讲解 ScyllaDB Commit Log 的全部 HTTP 接口如何查询活跃段、恢复指定文件、获取磁盘占用与任务队列指标并深入剖析每个接口背后的实现原理与配置参数的对应关系。读完本文你将能够直接调用这些 API 对运行中的 ScyllaDB 节点进行 Commit Log 巡检、恢复与排障。Commit Log 接口概览ScyllaDB 的 HTTP API 遵循 Swagger 1.2 规范接口定义位于 api/api-doc/commitlog.json路由注册实现在 api/commitlog.cc 的set_commitlog()函数中。全部接口以{{Protocol}}://{{Host}}为基地址即节点的 HTTP API 地址与端口默认 10000返回application/json格式。完整接口清单如下方法路径说明返回类型POST/commitlog/recover/{path}恢复指定文件或目录voidGET/commitlog/segments/active活跃 commit log 段文件名列表含未刷盘数据的段arraystringGET/commitlog/segments/archiving等待归档尝试的文件列表不含失败的归档尝试arraystringGET/commitlog/metrics/completed_tasks已完成的提交任务数longGET/commitlog/metrics/pending_tasks待处理的提交任务数longGET/commitlog/metrics/total_commit_log_sizecommit log 总大小longGET/commitlog/metrics/max_disk_size最大磁盘占用限制longGET/commit_log/metrics/waiting_on_segment_allocation等待段分配的耗时直方图histogramGET/commit_log/metrics/waiting_on_commit等待提交的耗时直方图histogram除此之外storage_service.json 中还定义了一个与 commit log 位置相关的接口GET /storage_service/commitlog用于返回 commit log 文件的存储位置其实现同样位于 api/commitlog.cc 中。注意路径中的大小写差异指标路径中活跃段、总大小等使用commitlog小写 l而两个直方图路径使用commit_log下划线调用时需严格区分。段文件管理接口活跃段与归档段查询活跃段GET /commitlog/segments/active活跃段指包含未刷盘unflushed数据的 commit log 段。该接口返回的是文件名而非完整路径。其底层实现在 api/commitlog.cchttpd::commitlog_json::get_active_segment_names.set(r, db { auto res make_sharedstd::vectorsstring(); return db.map_reduce(res { res-insert(res-end(), names.begin(), names.end()); }, [](replica::database db) { if (db.commitlog() nullptr) { return make_ready_futurestd::vectorsstring(std::vectorsstring()); } return make_ready_futurestd::vectorsstring(db.commitlog()-get_active_segment_names()); }).then([res] { return make_ready_futurejson::json_return_type(*res.get()); }); });实现要点通过db.map_reduce对所有 shard 上的 database 实例进行聚合将各 shard 返回的活跃段名合并成一个列表——ScyllaDB 是 shard-per-core 架构每个 shard 拥有独立的 commit log 段文件当db.commitlog() nullptr时例如 schema commit log 场景或测试环境直接返回空列表底层的get_active_segment_names()定义于 db/commitlog/commitlog.hh。请求示例curl -X GET http://localhost:10000/commitlog/segments/active响应示例JSON 数组[CommitLog-4-1736895600000.log, CommitLog-4-1736895660000.log]关于段文件命名docs/dev/commitlog-file-format.md 给出了规范段文件命名为Prefixversion-id.log其中Prefix通常为CommitLog-文件被回收复用时前缀为Recycled-Commitlog-version是文件格式版本号id是 replay position 的 id 部分由时间戳与 shard 编号组成。例如CommitLog-4-1736895600000.log表示格式版本 4、基于某个时间戳生成的段文件。归档段接口GET /commitlog/segments/archiving该接口在 API 规范中定义为返回等待归档尝试的文件列表不包含归档失败的文件。但从源码看ScyllaDB 当前实现直接返回空列表// We currently do not support archive segments httpd::commitlog_json::get_archiving_segment_names.set(r, [](const_req req) { std::vectorsstring res; return res; });这段注释api/commitlog.cc明确说明ScyllaDB 当前不支持段归档archive功能因此该接口保留仅为兼容 API 规范调用总是得到[]。了解这一点可以避免在排查问题时误以为归档队列异常。手动恢复接口POST /commitlog/recover/{path}该接口用于恢复单个 commit log 文件或整个目录。调用方式curl -X POST http://localhost:10000/commitlog/recover/var/lib/scylla/commitlog参数说明来自 commitlog.jsonpath必填path 参数Full path of file or directory即待恢复文件或目录的完整路径支持同时传入多个值allowMultiple: true返回类型为void。该接口与节点停机时的 commit log 重放机制同源ScyllaDB 启动时会扫描 commit log 目录将尚未刷盘的变更按 replay position 顺序重放回 Memtable具体实现在 db/commitlog/commitlog_replayer.cc 与 db/commitlog/commitlog_replayer.hh。从 storage_service.json 可见POST /storage_service/drain等运维操作描述中同样提到flush memtables and replays commitlog说明重放是 ScyllaDB 恢复流程的统一动作。需要提醒的是recover接口属于面向测试与应急场景的底层维护接口日常生产环境中 commit log 的重放由节点启动流程自动完成一般不需要手工调用。指标接口任务队列与磁盘占用/commitlog/metrics/*一组接口用于监控 commit log 的工作负载与磁盘压力全部经由acquire_cl_metric模板辅助函数实现。该函数对每个 shard 的 database 执行map_reduce0聚合将各 shard 的指标累加求和且同样处理了commitlog() nullptr的空值场景api/commitlog.cctemplatetypename T static auto acquire_cl_metric(shardedreplica::database db, std::functionT (const db::commitlog*) func) { return db.map_reduce0(func std::move(func) { if (db.commitlog() nullptr) { return make_ready_futureret_type(); } return make_ready_futureret_type(func(db.commitlog())); }, ret_type(), std::plusret_type()).then(...); }各指标接口与底层方法的对应关系如下表HTTP 接口底层方法db/commitlog/commitlog.hh含义/commitlog/metrics/completed_tasksget_completed_tasks()L325已完成的提交任务数/commitlog/metrics/pending_tasksget_pending_tasks()L327待处理的提交任务数/commitlog/metrics/total_commit_log_sizeget_total_size()L323当前 commit log 占用的总磁盘大小/commitlog/metrics/max_disk_sizedisk_limit()L365commit log 允许占用的最大磁盘空间监控建议pending_tasks持续偏高且伴随waiting_on_commit直方图延迟上升说明提交路径出现积压需要关注磁盘 I/O 与刷盘策略total_commit_log_size逼近max_disk_size时commit log 会触发刷盘回调flush_handler见 db/commitlog/commitlog.hh强制将最旧段对应的 Memtable 刷盘以释放段空间此时写入延迟可能升高。直方图指标waiting_on_segment_allocation 与 waiting_on_commit这两个接口路径中的下划线风格/commit_log/metrics/...与其余接口不同返回类型为#/utils/histogram即 seastar HTTP 框架的直方图结构包含均值、分位数等统计数据。它们分别刻画waiting_on_segment_allocation等待分配新段文件的时间分布——当段空间不足、需要预分配或回收段时写入方可能被阻塞等待waiting_on_commit等待提交完成的时间分布——在batch同步模式下写请求必须等 fsync 完成才被确认该直方图直接反映磁盘提交延迟。两个直方图均定义了底层指标访问方法get_num_blocked_on_new_segment()与get_pending_flushes()见 db/commitlog/commitlog.hh可供交叉验证。存储位置接口GET /storage_service/commitlog该接口返回 commit log 文件的存储位置目录字符串注册在 storage_service 路由下storage_service.json但实现在 api/commitlog.ccss::get_commitlog.set(r, db { return db.local().commitlog()-active_config().commit_log_location; });它直接读取commitlog::config::commit_log_locationdb/commitlog/commitlog.hh该值由 ScyllaDB 配置文件中的commitlog_directory决定默认指向/var/lib/scylla/commitlog见 conf/scylla.yaml。注意此处返回的是本 sharddb.local()的配置值未做跨 shard 聚合。请求示例curl -X GET http://localhost:10000/storage_service/commitlog关键配置参数与底层实现了解 REST API 之后掌握对应的配置文件参数conf/scylla.yaml能让你更精准地解读指标数据。与 commit log 相关的核心配置及其默认值如下配置项默认值作用commitlog_syncperiodic同步模式periodic或batchcommitlog_sync_period_in_ms10000periodic 模式下每次 fsync 的间隔毫秒commitlog_sync_batch_window_in_ms2注释示例batch 模式下等待其他写入再执行同步的窗口commitlog_segment_size_in_mb32yaml/64代码默认单个段文件大小schema_commitlog_segment_size_in_mb128schema commit log 段大小commitlog_total_space_in_mb-1无限制commit log 总空间上限commitlog_flush_threshold_in_mb自动推导触发刷盘的磁盘用量阈值commitlog_data_max_lifetime_in_seconds未设置段数据最大存活时间各参数在 db/config.cc 中有完整的语义注释关键点同步模式决定确认时机与直方图含义periodic模式下写入立即被确认由定时器commitlog_sync_period_in_ms默认 10000ms周期执行磁盘同步batch模式下写入必须等待 fsync 完成才确认因此waiting_on_commit直方图在 batch 模式下才是衡量写入确认延迟的关键指标。这两种模式对应底层 db/commitlog/commitlog.hh 的sync_mode枚举PERIODIC/BATCH段大小commitlog_segment_size_in_mb在 yaml 中默认 32MB而代码结构体默认值db/commitlog/commitlog.hh为 64MB实际生效值以配置为准schema commit log 使用独立的段大小配置且位于独立的目录schema_commitlog_directory默认/var/lib/scylla/commitlog/schema见 conf/scylla.yaml空间上限与刷盘联动commitlog_total_space_in_mb对应 API 中的max_disk_size指标当磁盘用量超过commitlog_flush_threshold_in_mb默认约为commitlog_total_space_in_mb - 节点数 × 段大小时ScyllaDB 会主动触发最旧段的 Memtable 刷盘并删除相应段从而将total_commit_log_size拉回安全区间。段文件格式与恢复原理源码纵深commit log 之所以能被安全重放得益于其带校验的段文件格式。ScyllaDB 当前使用版本 4current_version segment_version_4见 db/commitlog/commitlog.hh文件结构细节记录在 docs/dev/commitlog-file-format.md文件头魔数(S24)|(C16)|(L8)|C、版本号、段 id 及 CRC32 校验Chunk 结构每个 chunk 记录下一 chunk 的文件偏移file_pos与校验值使重放器在遇到数据损坏时可以跳过损坏 chunk 继续恢复Entry 结构每条数据条目由size、crc、数据体构成用于校验单条写入的完整性多条目Multi-entry以0xffffffff魔数标记多条记录合并为一次写入版本 4 的分片条目Fragmented entry以0xfffffffe魔数标记允许单条大记录跨多个段分片写入每片携带流 id、偏移与剩余长度重放器通过replay_state状态缓存并按序组装db/commitlog/commitlog.hh。版本 4 的关键改进在于每个磁盘块都带段 id 标签与 CRC块尾部 8 字节段 id 4 字节 CRC。由此重放器可以区分三类情况docs/dev/commitlog-file-format.mdCRC 损坏 → 该部分文件确实损坏可能丢失数据CRC 正确但段 id 不匹配 → 文件未完全写入或提前结束例如回收复用旧文件时的残留校验全部通过 → 数据可信。重放时read_log_file()db/commitlog/commitlog.hh按 replay position 顺序逐段读取将数据重新注入对应表。Commit log 只保证可恢复不保证写入顺序与调用者提交顺序一致——真实的先后顺序由返回的replay_position唯一标识见 db/commitlog/commitlog.hh 的类注释。使用场景与 FAQ何时使用这些 API写入路径巡检周期性调用completed_tasks/pending_tasks与两个直方图接口判断 commit log 提交是否积压磁盘压力监控对比total_commit_log_size与max_disk_size评估刷盘阈值触发频率进而调整commitlog_flush_threshold_in_mb或commitlog_total_space_in_mb崩溃后人工恢复在测试或排障场景下用POST /commitlog/recover/{path}对特定段文件或整个目录执行手动重放确认存储位置通过GET /storage_service/commitlog核实节点实际使用的 commit log 目录便于与监控、备份脚本对齐。常见问题为什么/commitlog/segments/archiving总是空数组ScyllaDB 当前不支持段归档接口仅为兼容保留api/commitlog.cc。为什么活跃段列表包含多个相似文件名ScyllaDB 是 shard-per-core 架构每个 shard 维护独立的段文件get_active_segment_names通过map_reduce聚合全部 shard 的结果。两个直方图接口路径为何带下划线这是 API 规范中的历史命名差异调用时需按/commit_log/metrics/...原样请求。手动 recover 是否会与自动重放冲突生产环境不建议在节点运行中随意调用 recover正常恢复流程由启动时的自动重放完成recover接口主要面向测试与隔离的应急场景。结语ScyllaDB Commit Log REST API 虽然只有 10 个端点但覆盖了段文件查询 → 手动恢复 → 任务队列与磁盘指标 → 存储位置的完整运维闭环。本文以 docs/reference/api/commit-log.rst 为纲逐条还原了 commitlog.json 的接口契约并通过 api/commitlog.cc 与 db/commitlog/commitlog.hh 的源码印证了每个接口的聚合逻辑与底层方法。配合 conf/scylla.yaml 中的配置项与 docs/dev/commitlog-file-format.md 的格式说明你可以快速搭建起一套针对 commit log 的巡检与排障方案。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考