ScyllaDB Nodetool tablestats 命令完全指南：语法、参数与输出字段详解
【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb
本文围绕 ScyllaDB 的nodetool tablestats命令展开，系统讲解它的语法规则（含 keyspace/table 分隔符与点号冲突的边界情况）、与cfstats的历史关系、全部输出字段的语义，以及它背后的 REST API 实现原理。读完本文，你将能准确调用该命令获取单表、单 keyspace 乃至全库的读写统计、SSTable 布局、Memtable 状态与 Bloom Filter 指标，并理解每个数字在运维排障中的实际含义。
命令概览
nodetool tablestats用于提供一张或多张表（table）的统计信息，是 ScyllaDB 运维中最常用来观察表级健康状态与读写负载的命令之一。它输出的指标覆盖五个层面：
- 读写负载：从上次启动以来的读/写次数与平均延迟；
- 存储占用：live SSTable、全部 SSTable 以及快照占用的磁盘空间；
- 内存占用：Memtable、Bloom Filter、Index Summary 与压缩元数据在堆外（off-heap）内存中的使用量；
- Compaction 状态：SSTable 数量、各 Level 的分布（针对 Leveled Compaction）；
- 扫描代价：最近五分钟内每次 slice 扫描的 live cells 与 tombstones 平均值/最大值，用于判断宽分区与墓碑堆积。
在 ScyllaDB 中，tablestats与cfstats是同一命令的别名关系：官方文档明确指出 cfstats 已被重命名为 nodetool tablestats，两者均可使用，例如nodetool cfstats等价于nodetool tablestats。在 scylla-nodetool.cc 的命令注册表中，"tablestats"的别名列表即包含{"cfstats"}。
语法与分隔符规则
nodetool tablestats [<keyspace.cfname>...]不带任何参数执行nodetool tablestats时，将输出集群中所有 keyspace 下所有表的统计信息，这也是文档给出的标准示例。
点号分隔与斜杠分隔
通常情况下，keyspace 与 cfname（table 名）之间用点号（.）分隔。但 ScyllaDB 允许 keyspace 名或表名本身包含点号，此时需要改用正斜杠（/）作为分隔符，避免歧义：
nodetool tablestats my.keyspace/my.cfname上例中my.keyspace是 keyspace 名，my.cfname是表名，二者内部均含有.，因此必须用/分隔。
只指定 keyspace 时的特殊规则
当你只想查看某个 keyspace 下所有表的统计（不指定具体表名），且该 keyspace 名含有.时，必须在 keyspace 名末尾追加一个/，以明确「斜杠前的整个字符串都是 keyspace 名」：
nodetool tablestats my.keyspace/如果不加末尾的/，nodetool 会把my.keyspace拆分为 keyspace=my、cfname=keyspace，从而得到完全不同的查询结果，甚至找不到目标表。
底层解析与过滤逻辑
从源码看，tablestats的位置参数通过typed_option<std::vector<sstring>>("tables", "List of tables (or keyspace) names", -1)接收（tools/scylla-nodetool.cc），数量不限（-1）。传入后由table_filter类负责匹配：它把用户给的每个keyspace.table说明解析成{keyspace → {table 集合}}映射，随后对每个 keyspace 逐表判断is_included(keyspace_name, table_name)（tools/scylla-nodetool.cc）：
- 若某 keyspace 在过滤器中存在但对应的表集合为空，表示该 keyspace 下的所有表都被选中；
- 若表集合非空，则只命中集合内指定的表。
这正是「只给 keyspace 名即可统计该 keyspace 全部表」的机制来源。
命令行选项
虽然文档正文未逐一列出，但tablestats在 ScyllaDB 的实现中支持三个实用选项（定义见 tools/scylla-nodetool.cc）：
| 选项 | 缩写 | 说明 |
|---|---|---|
--ignore | -i | 忽略给定的表列表，输出其余所有表的统计（反向过滤） |
--human-readable | -H | 以人类可读形式显示字节数（KiB、MiB、GiB、TiB） |
--format | -F | 输出格式，取值为plain（默认）、json或yaml |
table_stats_operation会读取这三个选项，并按格式分派到不同的打印实现（tools/scylla-nodetool.cc）：json走table_stats_print<json_writer>、yaml走table_stats_print<yaml_writer>、其余情况走table_stats_print_plain。若指定--ignore，table_filter会进入 exclusive 模式，命中过滤器的表被排除，未命中的表全部输出。
示例输出解读
执行nodetool tablestats（示例针对 keyspacekeyspace1中的表standard1）会得到如下分层输出：
Keyspace: keyspace1 Read Count: 0 Read Latency: NaN ms. Write Count: 41656 Write Latency: 0.016199467063568274 ms. Pending Flushes: 0 Table: standard1 SSTable count: 17 SSTables in each level: [ ] Space used (live): 28331544 Space used (total): 38060888 Space used by snapshots (total): 0 Off heap memory used (total): 5505072 SSTable Compression Ratio: 0.0 Number of partitions (estimate): 26829 Memtable cell count: 4868 Memtable data size: 4128083 Memtable off heap memory used: 4980736 Memtable switch count: 0 Local read count: 0 Local read latency: NaN ms Local write count: 41656 Local write latency: 0.014 ms Pending flushes: 0 Bloom filter false positives: 0 Bloom filter false ratio: 0.00000 Bloom filter space used: 0 Bloom filter off heap memory used: 524336 Index summary off heap memory used: 0 Compression metadata off heap memory used: 0 Compacted partition minimum bytes: 259 Compacted partition maximum bytes: 310 Compacted partition mean bytes: 310 Average live cells per slice (last five minutes): 0.0 Maximum live cells per slice (last five minutes): 0.0 Average tombstones per slice (last five minutes): 0.0 Maximum tombstones per slice (last five minutes): 0.0输出分两级：先给出 keyspace 级别的聚合统计（Read Count、Write Count、Pending Flushes 等），再给出其中每张表的详细统计（Table 之后的所有字段）。这与table_stats_print_plain的实现一致——它先遍历get_ks_to_cfs(client)得到 keyspace→表映射，把每张表累加进keyspace_stats，打印 keyspace 汇总后再逐表打印（tools/scylla-nodetool.cc）。
输出字段完整释义
以下为全部输出字段的语义对照（来自官方文档，字段名与输出一一对应）：
| 字段 | 含义 |
|---|---|
| Keyspace | keyspace 名称 |
| Read Count | 自上次启动以来的读取总次数 |
| Read Latency | 平均读延迟 |
| Write Count | 自上次启动以来的写入总次数 |
| Write Latency | 平均写延迟 |
| Pending Flushes | 已开始但尚未完成的 flush 数量 |
| Table | 表名 |
| SSTable count | 存活（live）SSTable 的数量 |
| SSTables in each level | 在 leveled compaction 下，报告每个 level 的 SSTable 数量与大小 |
| Space used (live) | live SSTable 占用的磁盘空间 |
| Space used (total) | 所有 SSTable 占用的磁盘空间 |
| Space used by snapshots (total) | 快照占用的磁盘空间 |
| Off heap memory used (total) | Memtable、Bloom Filter、Index Summary 与压缩元数据占用的内存之和 |
| SSTable Compression Ratio | SSTable 压缩比率 |
| Number of partitions (estimate) | 基于估计直方图（estimated histogram）的分区数估计值 |
| Memtable cell count | Memtable 中的列（cell）数量 |
| Memtable data size | 存活 Memtable 已使用的空间 |
| Memtable off heap memory used | 所有 Memtable 占用的内存；在 ScyllaDB 中所有内存都在堆外（off heap） |
| Memtable switch count | SSTable 被切换（即被 flush）的次数 |
| Local read count | 读操作次数 |
| Local read latency | 平均读操作耗时 |
| Local write count | 写操作次数 |
| Local write latency | 平均写操作耗时 |
| Pending flushes | 等待被 flush 的 SSTable 数量 |
| Bloom filter false positives | Bloom Filter 产生的误判（false positive）次数 |
| Bloom filter false ratio | 误判次数与总查询次数之比 |
| Bloom filter space used | Bloom Filter 占用的内存 |
| Bloom filter off heap memory used | Bloom Filter 堆外内存占用（ScyllaDB 中全部为堆外） |
| Index summary off heap memory used | Index Summary 占用的内存 |
| Compression metadata off heap memory used | 压缩元数据占用的堆外内存 |
| Compacted partition minimum bytes | 压缩后分区的最小字节数 |
| Compacted partition maximum bytes | 压缩后分区的最大字节数 |
| Compacted partition mean bytes | 压缩后分区的平均字节数 |
| Average live cells per slice (last five minutes) | 最近五分钟内每次 slice 扫描的平均 live cells 数 |
| Maximum live cells per slice (last five minutes) | 最近五分钟内每次 slice 扫描的最大 live cells 数 |
| Average tombstones per slice (last five minutes) | 最近五分钟内每次 slice 扫描的平均 tombstones 数 |
| Maximum tombstones per slice (last five minutes) | 最近五分钟内每次 slice 扫描的最大 tombstones 数 |
使用提示
- Read Latency 为
NaN ms.属正常现象：当 Read Count 为 0（从未发生过读取）时，平均延迟无样本可计算，会显示NaN；同理 Local read latency 也会是NaN。 - Memtable 指标揭示写入缓冲状态：
Memtable cell count与Memtable data size反映尚未落盘的写入数据量；Pending Flushes非零通常说明后台 flush 排队，可能伴随写入压力或磁盘瓶颈。 - Bloom Filter 三项指标用于排查读放大：
Bloom filter false positives、false ratio与space used一起看，false ratio 偏高意味着大量查询需要穿透 Bloom Filter 去读磁盘索引，常见诱因是 Bloom Filter 空间不足或表近期大量写入导致误判率上升。 - tombstones 指标用于识别墓碑堆积：
Average/Maximum tombstones per slice明显升高，提示该表存在高频更新/删除造成的墓碑堆积，可能拖慢读路径，需要考虑 compaction 策略与 TTL 配置。 - Compacted partition 字节数用于评估分区大小：mean bytes 与 maximum bytes 差距悬殊时，说明存在大小极不均衡的分区，可能引发热点。
底层实现：REST API 数据通路
tablestats并非直接读取 ScyllaDB 本地数据结构，而是通过 REST API 与 ScyllaDB 节点通信。从table_stats_operation的调用链可以看到：
- 客户端调用
client.get("/column_family/")获取全部表列表，输出Total number of tables； - 对每个 keyspace，按表逐个请求
/column_family/metrics/{metric_name}/moving_average_histogram/{keyspace}:{table}拉取read_latency、write_latency等直方图数据（tools/scylla-nodetool.cc）； - 其余指标（SSTable 数量、空间、Bloom Filter、Memtable 等）同样来自
/column_family/系列 REST 端点，例如 Bloom Filter 误判计数由cf::get_bloom_filter_false_positives路由提供（api/column_family.cc）。
在 plain 输出中，各内存类字段会经过file_size_printer处理，配合--human-readable选项即可显示为 KiB/MiB/GiB/TiB 形式；--format json/yaml则把同样的数据映射为结构化字段（键名形如sstables_in_each_level、off_heap_memory_used_total、average_live_cells_per_slice_last_five_minutes等，见 tools/scylla-nodetool.cc），便于脚本与监控系统消费。
关于 Leveled Compaction 的 level 输出
SSTables in each level字段在源码中通过print_ss_table_levels生成，其阈值遵循 LCS 的 fanout 规则：level 0 上限 4 个 SSTable，level 1 上限 10 个，此后每升一级乘以 10（LEVEL_FANOUT_SIZE = 10）（tools/scylla-nodetool.cc）。当某个 level 的 SSTable 数量超过上限时，会以count/max_count的形式（如12/10）提示该 level 积压、需要 compaction 追赶；示例输出中为[ ]，说明该表未启用 leveled compaction 或当前没有按 level 划分的 SSTable。
与其他 nodetool 命令的关系
nodetool cfstats：已重命名为tablestats的旧名，功能完全等价，文档见 cfstats.rst。nodetool cfhistograms：同样以表为单位输出读/写延迟与 row size 的直方图分布，与tablestats的「均值/总数」视角互补，适合分析延迟分布尾部（文档见 cfhistograms.rst）。nodetool compactionstats/compactionhistory：当Pending flushes、level 积压或 SSTable count 持续增长时，可结合它们观察 compaction 是否跟上写入速率。
完整的 nodetool 命令索引参见 nodetool-index.rst 与 nodetool 参考文档（若存在）。
【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
