Telegraf Couchbase 输入插件采集 Couchbase 集群节点与 Bucket 指标的完整指南【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本指南围绕 Telegraf 的inputs.couchbase输入插件展开讲解如何通过它采集 Couchbase分布式 NoSQL 数据库每个节点node与每个 Bucket 的详细指标。读完本文你将掌握插件的完整配置项、底层 REST 采集原理、全部输出指标measurement/tags/fields的含义与单位以及如何结合实际测试用例验证采集结果从而构建起一套可落地的 Couchbase 集群监控方案。插件概述couchbase输入插件位于 plugins/inputs/couchbase/从 Telegraf v0.12.0 起可用分类为 server 型输入支持在所有平台上运行。它通过 Couchbase 的 REST 管理接口为指定的 Couchbase 服务器采集两类指标每节点per-node指标集群中各节点的内存使用情况每 Bucketper-bucket指标集群范围内以及单个节点视角下的 Bucket 详细统计。采集到的指标以couchbase_node、couchbase_bucket、couchbase_node_bucket、couchbase_autofailover四种 measurement 写入下游可无缝衔接 InfluxDB、Prometheus 等输出端。插件配置完整示例与参数详解最小可用配置[[inputs.couchbase]] servers [http://localhost:8091]仅配置servers即可开始采集。默认行为如下源自 sample.conf 与 couchbase.go 源码若不指定任何服务器插件会回退到http://localhost:8091/若不指定协议默认使用 HTTP若不指定端口默认使用8091Couchbase 管理 REST 端口服务器地址支持[protocol://][:password]address[:port]形式如http://admin:secretcouchbase-0.example.com:8091/。完整配置示例# Read per-node and per-bucket metrics from Couchbase [[inputs.couchbase]] ## specify servers via a url matching: ## [protocol://][:password]address[:port] ## e.g. ## http://couchbase-0.example.com/ ## http://admin:secretcouchbase-0.example.com:8091/ ## ## If no servers are specified, then localhost is used as the host. ## If no protocol is specified, HTTP is used. ## If no port is specified, 8091 is used. servers [http://localhost:8091] ## Filter bucket fields to include only here. # bucket_stats_included [quota_percent_used, ops_per_sec, disk_fetches, item_count, disk_used, data_used, mem_used] ## Optional TLS Config # tls_ca /etc/telegraf/ca.pem # tls_cert /etc/telegraf/cert.pem # tls_key /etc/telegraf/key.pem ## Use TLS but skip chain host verification (defaults to false) ## If set to false, tls_cert and tls_key are required # insecure_skip_verify false ## Whether to collect cluster-wide bucket statistics ## It is recommended to disable this in favor of node_stats ## to get a better view of the cluster. # cluster_bucket_stats true ## Whether to collect bucket stats for each individual node # node_bucket_stats false ## List of additional stats to collect, choose from: ## * autofailover # additional_stats []配置项逐一说明配置项类型默认值说明serversstring 数组[http://localhost:8091]一个或多个 Couchbase 集群地址。支持协议、用户密码、端口组合插件会为每个 server 并发发起采集bucket_stats_includedstring 数组7 个默认字段见下白名单过滤 Bucket 字段。通过 filter.NewIncludeExcludeFilter 构建 include 过滤器未列出的字段不会进入输出tls_ca/tls_cert/tls_keystring空可选 TLS 配置指向 PEM 证书文件路径用于 HTTPS 场景insecure_skip_verifyboolfalse设为 true 时跳过证书链与主机名校验若为 false则tls_cert与tls_key为必填cluster_bucket_statsbooltrue是否采集集群范围内的 Bucket 统计。官方注释建议在多节点场景下关闭它改用node_bucket_stats以获得更细粒度的集群视图node_bucket_statsboolfalse是否采集每个独立节点视角的 Bucket 统计产生couchbase_node_bucketmeasurementadditional_statsstring 数组[]额外统计列表当前支持autofailover用于采集 Couchbase 自动故障转移设置注意bucket_stats_included的默认值为[quota_percent_used, ops_per_sec, disk_fetches, item_count, disk_used, data_used, mem_used]该默认值直接写在 couchbase.go 的 init() 函数 中与ClusterBucketStats: true一起作为插件默认状态。多集群与认证场景servers支持数组因此可以同时监控多个 Couchbase 集群[[inputs.couchbase]] servers [ http://admin:secretcouchbase-0.example.com:8091/, http://couchbase-1.example.com:8091/, ]插件在 Gather 中为每个 server 启动一个 goroutine 并发采集并通过acc.AddError汇聚错误单点故障不会阻断整体采集。cluster标签取自servers配置中去除认证信息的净化后地址正则(\S://)?(\S\:\S)会剥离user:password部分因此即使多个集群使用相同 bucket 名也能通过cluster标签区分数据来源。底层实现采集流程与 REST 接口理解插件如何工作有助于排查采集异常。核心逻辑集中在 gatherServer一次完整的采集包含以下步骤连接与获取默认 Pool调用couchbase.Connect(addr)建立连接然后client.GetPool(default)获取默认资源池。default是当前唯一可能的 pool 名称代码注释中说明它是为 Couchbase 未来可能的功能预留的占位符采集节点内存指标遍历pool.Nodes将每个节点的MemoryFree、MemoryTotal作为字段以节点Hostname为标签写入couchbase_node采集 Bucket 指标遍历pool.BucketMap若ClusterBucketStats开启调用gatherDetailedBucketStats请求/pools/default/buckets/bucket/stats写入couchbase_bucket若NodeBucketStats开启对每个节点请求/pools/default/buckets/bucket/nodes/hostname/stats写入couchbase_node_bucket采集额外统计若additional_stats包含autofailover通过 HTTP GET 请求/settings/autoFailover接口见 gatherAutoFailoverStats解析 JSON 后写入couchbase_autofailover。插件内部维护一个http.Client超时 10 秒其 TLS 配置与连接池MaxIdleConnsPerHost取自 go-couchbase 常量在 Init() 中初始化。值得注意的是TLS 证书相关设置会同时透传给底层 go-couchbase 库SetSkipVerify/SetCertFile/SetKeyFile/SetRootFile确保认证凭据与 TLS 配置在连接和 HTTP 请求两条路径上保持一致。/pools/default/buckets/bucket/stats接口返回的samples是时间序列数组插件在 addBucketFieldChecked 中只取数组最后一个采样值values[len(values)-1]作为当前指标值若采样数组为 nil接口未返回该指标则直接跳过不会写入零值。输出指标详解couchbase_node节点级指标Tagscluster来自servers配置的净化地址例如http://user:passwordcouchbase-0.example.com:8091/endpoint会变成http://couchbase-0.example.com:8091/endpointhostnameCouchbase 对节点的命名含端口如172.16.10.187:8091。Fieldsmemory_free单位bytes示例23181365248.0节点可用内存memory_total单位bytes示例64424656896.0节点总内存。couchbase_autofailover自动故障转移设置Tagscluster同上为净化后的服务器地址。Fieldscount单位int示例1已发生的故障转移次数enabled单位bool示例true自动故障转移是否启用max_count单位int示例2最大故障转移次数timeout单位int示例72故障转移判定超时秒。对应的数据结构定义在 couchbase.goJSON 字段映射为count/enabled/maxCount/timeout可从/settings/autoFailover接口返回内容见 settings_autofailover.json印证。couchbase_bucket 与 couchbase_node_bucketBucket 级指标Tagsclusterservers中配置的地址例如http://couchbase-0.example.com/bucketCouchbase Bucket 名称例如blastro-dfhostname采集到该 Bucket 指标的节点主机名例如172.16.10.187:8091仅存在于couchbase_node_bucket。默认字段对应bucket_stats_included的默认值字段单位示例值quota_percent_usedpercent68.85424936294555ops_per_seccount5686.789686789687disk_fetchescount0.0item_countcount943239752.0disk_usedbytes409178772321.0data_usedbytes212179309111.0mem_usedbytes202156957464.0可通过bucket_stats_included启用的附加字段完整清单与 README 保持一致容量与碎片couch_total_disk_size、couch_docs_fragmentation、couch_views_fragmentation、couch_docs_actual_disk_size、couch_docs_data_size、couch_docs_disk_size、couch_spatial_data_size、couch_spatial_disk_size、couch_spatial_ops、couch_views_actual_disk_size、couch_views_data_size、couch_views_disk_size、couch_views_ops命中率与驻留率hit_ratio、ep_cache_miss_rate、ep_resident_items_rate、vb_active_resident_items_ratio、vb_replica_resident_items_ratio、vb_pending_resident_items_ratio队列年龄vb_avg_active_queue_age、vb_avg_replica_queue_age、vb_avg_pending_queue_age、vb_avg_total_queue_age、vb_active_queue_age、vb_active_queue_drain、vb_active_queue_fill、vb_active_queue_size、vb_pending_queue_age、vb_pending_queue_drain、vb_pending_queue_fill、vb_pending_queue_size、vb_replica_queue_age、vb_replica_queue_drain、vb_replica_queue_fill、vb_replica_queue_size、vb_total_queue_age磁盘与后台等待avg_disk_update_time、avg_disk_commit_time、avg_bg_wait_time、bg_wait_count、bg_wait_total、disk_commit_count、disk_commit_total、disk_update_count、disk_update_total、disk_write_queue、ep_diskqueue_drain、ep_diskqueue_fill、ep_diskqueue_items、ep_flusher_todo、ep_bg_fetched、ep_data_read_failed、ep_data_write_failed、ep_item_commit_failedHLC 时钟漂移avg_active_timestamp_drift、avg_replica_timestamp_drift、ep_active_ahead_exceptions、ep_active_hlc_drift、ep_active_hlc_drift_count、ep_clock_cas_drift_threshold_exceeded、ep_replica_ahead_exceptions、ep_replica_hlc_drift、ep_replica_hlc_drift_countDCPviewsindexesep_dcp_viewsindexes_count、ep_dcp_viewsindexes_items_remaining、ep_dcp_viewsindexes_producer_count、ep_dcp_viewsindexes_total_backlog_size、ep_dcp_viewsindexes_items_sent、ep_dcp_viewsindexes_total_bytes、ep_dcp_viewsindexes_backoffDCP2i 二级索引ep_dcp_2i_backoff、ep_dcp_2i_count、ep_dcp_2i_items_remaining、ep_dcp_2i_items_sent、ep_dcp_2i_producer_count、ep_dcp_2i_total_backlog_size、ep_dcp_2i_total_bytesDCPCBAS / Analyticsep_dcp_cbas_backoff、ep_dcp_cbas_count、ep_dcp_cbas_items_remaining、ep_dcp_cbas_items_sent、ep_dcp_cbas_producer_count、ep_dcp_cbas_total_backlog_size、ep_dcp_cbas_total_bytesDCPEventingep_dcp_eventing_backoff、ep_dcp_eventing_count、ep_dcp_eventing_items_remaining、ep_dcp_eventing_items_sent、ep_dcp_eventing_producer_count、ep_dcp_eventing_total_backlog_size、ep_dcp_eventing_total_bytesDCPFTS 全文检索ep_dcp_fts_backoff、ep_dcp_fts_count、ep_dcp_fts_items_remaining、ep_dcp_fts_items_sent、ep_dcp_fts_producer_count、ep_dcp_fts_total_backlog_size、ep_dcp_fts_total_bytesDCPOtherep_dcp_other_backoff、ep_dcp_other_count、ep_dcp_other_items_remaining、ep_dcp_other_items_sent、ep_dcp_other_producer_count、ep_dcp_other_total_backlog_size、ep_dcp_other_total_bytesDCPReplicaep_dcp_replica_backoff、ep_dcp_replica_count、ep_dcp_replica_items_remaining、ep_dcp_replica_items_sent、ep_dcp_replica_producer_count、ep_dcp_replica_total_backlog_size、ep_dcp_replica_total_bytesDCPViewsep_dcp_views_backoff、ep_dcp_views_count、ep_dcp_views_items_remaining、ep_dcp_views_items_sent、ep_dcp_views_producer_count、ep_dcp_views_total_backlog_size、ep_dcp_views_total_bytesDCPXDCR 跨数据中心复制ep_dcp_xdcr_backoff、ep_dcp_xdcr_count、ep_dcp_xdcr_items_remaining、ep_dcp_xdcr_items_sent、ep_dcp_xdcr_producer_count、ep_dcp_xdcr_total_backlog_size、ep_dcp_xdcr_total_bytes网络与命令bytes_read、bytes_written、cmd_get、cmd_lookup、cmd_set、curr_connections、curr_items、curr_items_tot、decr_hits、decr_misses、delete_hits、delete_misses、get_hits、get_misses、incr_hits、incr_misses、mem_used、misses、ops、xdc_opsCAS 操作cas_badval、cas_hits、cas_misses内存管理ep_kv_size、ep_max_size、ep_mem_high_wat、ep_mem_low_wat、ep_meta_data_memory、ep_num_non_resident、ep_num_value_ejects、ep_oom_errors、ep_overhead、ep_queue_size、ep_tmp_oom_errors、ep_vb_total、evictionsMeta 操作ep_num_ops_del_meta、ep_num_ops_del_ret_meta、ep_num_ops_get_meta、ep_num_ops_set_meta、ep_num_ops_set_ret_meta增删改计数ep_ops_create、ep_ops_updatevBucket 状态active/pending/replicavb_active_eject、vb_active_itm_memory、vb_active_meta_data_memory、vb_active_num、vb_active_num_non_resident、vb_active_ops_create、vb_active_ops_update、vb_active_sync_write_aborted_count、vb_active_sync_write_accepted_count、vb_active_sync_write_committed_count、vb_pending_curr_items、vb_pending_eject、vb_pending_itm_memory、vb_pending_meta_data_memory、vb_pending_num、vb_pending_num_non_resident、vb_pending_ops_create、vb_pending_ops_update、vb_replica_curr_items、vb_replica_eject、vb_replica_itm_memory、vb_replica_meta_data_memory、vb_replica_num、vb_replica_num_non_resident、vb_replica_ops_create、vb_replica_ops_update系统与 CPUallocstall、cpu_cores_available、cpu_irq_rate、cpu_stolen_rate、cpu_sys_rate、cpu_user_rate、cpu_utilization_rate内存与交换hibernated_requests、hibernated_waked、mem_actual_free、mem_actual_used、mem_free、mem_limit、mem_total、mem_used_sys、swap_total、swap_used其他timestamp、odp_report_failed、rest_requests这些字段与 couchbase_data.go 中bucketStats结构体的Samples字段一一对应JSON tag 即 Couchbase 原生指标名并且在 gatherDetailedBucketStats 中被逐个映射为 Telegraf 字段名。示例输出开启默认配置cluster_bucket_stats true默认 7 个字段时一次采集产生如下行协议输出时间戳为纳秒couchbase_node,clusterhttp://localhost:8091/,hostname172.17.0.2:8091 memory_free7705575424,memory_total16558182400 1547829754000000000 couchbase_bucket,bucketbeer-sample,clusterhttp://localhost:8091/ quota_percent_used27.09285736083984,ops_per_sec0,disk_fetches0,item_count7303,disk_used21662946,data_used9325087,mem_used28408920 1547829754000000000可见节点指标每节点一条记录Bucket 指标每条记录包含默认的 7 个字段cluster与bucket/hostname标签共同构成了可查询的唯一标识。测试与验证源码如何保证采集正确性仓库内 couchbase_test.go 使用httptest模拟 Couchbase 服务端覆盖了采集主路径与关键边界TestGatherServer模拟/pools、/pools/default、/pools/default/buckets与/pools/default/buckets/blastro-df/stats四个接口断言couchbase_node与couchbase_bucket的字段与标签完全符合预期数据来自 testdata 下的真实结构 JSONTestSanitizeURI验证 URI 净化正则能正确处理带用户名密码、仅主机名、带协议、带路径等各类 server 地址格式TestGatherDetailedBucketMetrics验证附加字段过滤只输出白名单内的字段且当接口返回缺失某些采样bucket_stats_response_with_missing.json或按节点查询node_bucket_stats_response.json时不会报错TestGatherNodeOnly验证全部关闭 Bucket 统计时只输出节点指标TestGatherFailover验证additional_stats [autofailover]时正确解析/settings/autoFailover的count/enabled/max_count/timeout四个字段其中enabled保持布尔类型。这些测试既是插件行为的规格说明也可作为你本地复现 Couchbase 指标采集逻辑的参考起点。实战建议单机快速验证先在servers [http://localhost:8091]基础上运行telegraf --config 你的配置 --test观察是否有couchbase_node与couchbase_bucket输出若为多节点集群建议按官方建议将cluster_bucket_stats设为false、node_bucket_stats设为true以获得更完整的集群视图控制字段数量samples中的附加字段多达 200 余个全部启用会显著增大输出数据量。建议按监控目标挑选字段加入bucket_stats_included例如只保留容量类quota_percent_used、disk_used、data_used、mem_used与性能类ops_per_sec、ep_bg_fetched、ep_cache_miss_rate、hit_ratioHTTPS 与认证若 Couchbase 管理端口启用 TLS务必配置tls_ca/tls_cert/tls_keyinsecure_skip_verify true仅建议在非生产环境使用多集群标签管理利用cluster标签区分多个集群的数据源若集群启用了认证请确认servers中凭据正确因为该凭据同时用于 go-couchbase 连接与/settings/autoFailover的 HTTP 请求告警场景couchbase_autofailover的enabled字段适合作为自动故障转移是否开启的告警依据timeout与max_count可用于校验配置是否符合运维规范。如需了解插件的全局配置能力如name_override、标签裁剪、字段裁剪、metricpass 过滤等可参考 docs/CONFIGURATION.md 中的插件通用配置说明。本文所述的配置、指标与行为均以当前仓库中的 README、couchbase.go 及 testdata 为准。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考