Couchbase作为一款分布式文档型数据库，其核心数据管理单元是bucket（桶）。每个bucket在运行过程中会产生大量的统计数据，这些数据是运维人员和开发者判断集群健康状况、定位性能瓶颈的最直接依据。理解bucket stats的各项指标含义，掌握正确的查看和分析方法，是用好Couchbase不可或缺的一环。
一、bucket stats的核心指标含义
Couchbase对每个bucket维护着上百项统计指标，可以从Web控制台的Bucket页面进入后查看实时图表。这些指标大致可以分为内存、磁盘、操作、副本四大类，每一类都反映了bucket运行的不同侧面。
内存类指标中最重要的几个是mem_used（当前已用内存）、quota_percent_used（配额使用百分比）和ep_num_value_ejects（被驱逐的item数量）。Couchbase采用内存优先的架构，数据先写入内存，再异步持久化到磁盘。当内存配额被占满时，引擎会根据淘汰策略将部分active item驱逐出内存，只保留磁盘副本。如果驱逐数量持续增长，说明内存配额偏小或工作集过大，读性能会明显下降。
操作类指标里，ops表示每秒总操作数，get_hits和get_misses分别代表读命中和读未命中次数。命中率是一个衍生指标，计算方式为get_hits除以两者之和。命中率长期低于95%通常意味着工作集超出了内存容量，或者应用访问模式过于分散。副本类指标如replica_ops和ep_resharding则反映了副本同步与vbucket迁移的活跃程度，在节点故障恢复或rebalance期间需要重点关注。
二、查看bucket stats的三种常用方式
第一种是Web控制台，进入Buckets页面后点击具体bucket名称，即可看到以图表形式展示的实时指标，可以自由切换时间范围，直观查看趋势变化。这种方式适合日常巡检和快速排查。
第二种是命令行工具cbstats，它位于Couchbase安装目录的bin目录下，例如Linux环境通常是/opt/couchbase/bin/cbstats。它直接从目标节点的数据服务端口拉取原始统计数据，输出非常全面：
# 查看某个bucket的全量统计数据 /opt/couchbase/bin/cbstats 127.0.0.1:11210 -u Administrator -p password -b travel-sample all # 只查看内存相关指标 /opt/couchbase/bin/cbstats 127.0.0.1:11210 -u Administrator -p password -b travel-sample memory # 查看vbucket分布情况 /opt/couchbase/bin/cbstats 127.0.0.1:11210 -u Administrator -p password -b travel-sample vbucket
其中11210是数据服务的默认端口，-b指定bucket名称，all表示输出全部统计分组，也可以换成memory、disk、kvstore、warmup等具体分组，只关注某一类指标。cbstats的输出是原始键值对形式，适合脚本化采集和精确定位。
第三种是REST API，通过curl访问8091端口的统计接口，可以获取JSON格式的指标数据，便于对接自建监控平台：
curl -u Administrator:password \ "http://127.0.0.1:8091/pools/default/buckets/travel-sample/stats"
返回的JSON中包含op.samples数组，每个指标对应一个按时间采样的数值序列，直接解析即可绘制自定义监控图表。需要注意的是，REST API返回的是集群聚合后的数据，而cbstats返回的是单节点本地数据，排查节点级问题时应结合两者对照分析。
三、结合stats排查常见问题的思路
内存不足是最常见的问题。典型表现是quota_percent_used长期接近100%，同时ep_num_value_ejects持续增加。此时应先确认bucket的内存配额是否合理，工作集大小是否超过配额。可以适当调大配额或增加节点，也可以评估业务上是否需要为不同数据热度分层设置不同bucket。
命中率下降问题需要结合item count和访问模式分析。如果get_misses比例升高，除了内存驱逐因素外，还可能是应用查询了不存在的key，或者过期策略设置不当导致大量item被删除。通过对比curr_items（当前item总数）和业务预期的数据量，可以快速判断是否存在异常删除。
磁盘IO瓶颈的表现是disk_inserts、disk_update的排队积压，以及avg_disk_commit_time升高。当写ops高峰超过磁盘flush能力时，内存中的待写队列会膨胀，极端情况下触发硬限流。排查时应查看queue_size相关指标，必要时降低写入压力、更换更高性能的磁盘，或增加节点分摊负载。另外在rebalance期间，ep_resharding和ep_num_ckpt_connections指标会明显升高，属于正常现象，但如果rebalance长时间不结束，就要检查网络吞吐是否成为瓶颈。
四、监控告警的实践建议
建议对几个关键指标设置告警阈值：内存配额使用率超过85%告警，命中率低于90%告警，待写队列持续增长告警，副本数量低于预期告警。Couchbase内置了Autofailover和部分阈值告警，但更细粒度的监控建议通过REST API采集数据后对接Prometheus等平台统一管理。
分析stats数据时要养成看趋势而不是看瞬时值的习惯。单点的内存高或命中率低未必是问题，持续的恶化趋势才是需要介入的信号。同时注意区分active指标和replica指标，很多同名指标会有active和replica两个版本，混用容易得出错误结论。掌握这些方法后，bucket stats就能从一堆枯燥的数字变成洞察集群运行状态的有力工具。
Couchbasebucket stats桶统计修改时间：2026-09-02 07:14:27