Apache CouchDB 监控采集插件深度解析：从 `_stats` 端点采集到 Telegraf 指标

2026-09-13 14:18:15作者：申梦珏Efrain

Apache CouchDB 是广泛使用的面向文档的 NoSQL 数据库，其运行健康度（认证缓存命中、数据库读写、HTTP 请求分布、各状态码数量等）是保障上层应用稳定性的关键观测数据。本篇技术指南基于 Telegraf 仓库中 couchdb 输入插件的官方文档，结合 couchdb.go 源码与 couchdb_test.go 测试用例，完整讲解该插件的配置方式、指标语义、标签规则、CouchDB 1.x 与 2.x 两种 API 差异的自动适配原理，以及多主机并发采集的底层实现。读完本文，你将能够独立完成 CouchDB 集群的 Telegraf 监控接入，并理解每个指标字段的来源与含义。

插件概览

该插件通过 CouchDB 自带的 _stats HTTP 端点读取服务端统计信息，无需安装额外组件，也不要求对 CouchDB 做任何侵入式配置。

属性	值
插件分类	输入插件（inputs）
引入版本	⭐ Telegraf v0.10.3
适用场景标签	🏷️ server
平台支持	💻 all（跨平台）
数据来源	CouchDB `_stats` 端点
注册入口	plugins/inputs/all/couchdb.go

在 Telegraf 的插件注册体系中，plugins/inputs/all/couchdb.go 通过 import _ "github.com/influxdata/telegraf/plugins/inputs/couchdb" 完成插件注册，其构建标签为 !custom \|\| inputs \|\| inputs.couchdb，意味着使用自定义构建（custom builder）时可通过该标签单独裁剪包含此插件。

配置说明

最小可用配置

在 telegraf.conf 中加入如下片段即可开始采集：

# 从一个或多个服务器读取 CouchDB 统计信息
[[inputs.couchdb]]
  ## 开箱即用地兼容 CouchDB stats 端点
  ## 可配置多个主机地址，逐一读取其 stats：
  hosts = ["http://localhost:8086/_stats"]

这份配置与仓库中的 sample.conf 完全一致，是插件对外暴露的官方示例模板。其中：

hosts（必填，字符串数组）：一个或多个 CouchDB stats 端点完整 URL。URL 必须包含 /_stats 路径，插件不会自动拼接。
开发调试目录 dev/telegraf.conf 给出了同时采集 CouchDB 1.x 与 2.x 的真实写法：

[[inputs.couchdb]]
  hosts = ["http://couchdb16:5984/_stats", "http://couchdb22:5984/_node/_local/_stats"]

注意 CouchDB 2.x 的 stats 端点路径与 1.x 不同（详见下文"版本适配"一节）。

HTTP Basic 认证

当 CouchDB 开启了认证（例如设置了 admin/password 的 require_valid_user 模式）时，可通过 Basic Auth 访问 stats 端点：

[[inputs.couchdb]]
  hosts = ["http://localhost:8086/_stats"]

  ## 使用 HTTP Basic Authentication
  # basic_username = "telegraf"
  # basic_password = "p@ssw0rd"

对应源码中 couchdb.go#L19-L25 的结构体定义：

type CouchDB struct {
	Hosts         []string `toml:"hosts"`
	BasicUsername string   `toml:"basic_username"`
	BasicPassword string   `toml:"basic_password"`

	client *http.Client
}

当 basic_username 或 basic_password 任一非空时，请求会携带 SetBasicAuth 头（见 couchdb.go#L132-L134）：

if c.BasicUsername != "" || c.BasicPassword != "" {
	req.SetBasicAuth(c.BasicUsername, c.BasicPassword)
}

全局配置选项

与 Telegraf 其他插件一样，inputs.couchdb 也支持作用于所有插件的全局配置能力，例如通过 namepass、fieldpass、tagexclude 等过滤器裁剪指标，使用 name_override 重命名测量名，或用 alias 创建别名、调整插件执行顺序。这些通用设置详见 docs/CONFIGURATION.md（官方文档中通过 docs/includes/plugin_config.md 片段统一引入）。以下是结合 namepass 使用的示例：

[[inputs.couchdb]]
  hosts = ["http://localhost:8086/_stats"]
  namepass = ["couchdb"]

HTTP 请求行为与错误处理

插件每次采集会向每个 host 发送一次 HTTP GET 请求，其底层客户端行为（couchdb.go#L117-L150）值得关注：

超时控制：HTTP 客户端设置了 ResponseHeaderTimeout: 3 * time.Second 与整体 Timeout: 4 * time.Second，避免 CouchDB 无响应时采集协程被永久阻塞。
状态码校验：仅接受 200 响应，其余状态码返回错误 failed to get stats from couchdb: HTTP responded %d。
JSON 解码：使用 json.Decoder 直接解码响应体到内部 stats 结构。
单点失败隔离：Gather 对每个 host 启动独立 goroutine（sync.WaitGroup 等待全部完成），单台 CouchDB 不可达不会阻塞其他主机的采集，错误通过 accumulator.AddError 上报（couchdb.go#L100-L115）。

测试用例 couchdb_test.go 使用 httptest.NewServer 模拟 /_stats 端点返回完整 JSON（含大量 null 字段的统计项），并通过 acc.GatherError(plugin.Gather) 断言采集过程无错误，验证了插件对"统计值缺失（null）"场景的健壮性。

指标详解

插件产出的测量名（measurement）统一为 couchdb，所有指标项按来源分组如下。

CouchDB 内部统计

反映 CouchDB 内核状态：

指标前缀	含义
`couchdb_auth_cache_misses`	认证缓存未命中次数
`couchdb_auth_cache_hits`	认证缓存命中次数
`couchdb_database_writes`	数据库被修改（写入）的次数
`couchdb_database_reads`	从数据库读取文档的次数
`couchdb_open_databases`	当前打开的数据库数量
`couchdb_open_os_files`	CouchDB 打开的文件描述符数量
`couchdb_request_time`	请求在 CouchDB 内部（不含 MochiWeb）的耗时

HTTP 请求方法统计

按 HTTP 动词维度统计请求量：

指标前缀	对应方法
`httpd_request_methods_put`	PUT
`httpd_request_methods_get`	GET
`httpd_request_methods_copy`	COPY
`httpd_request_methods_delete`	DELETE
`httpd_request_methods_post`	POST
`httpd_request_methods_head`	HEAD

HTTP 状态码统计

按响应状态码统计：

httpd_status_codes_200、_201、_202、_301、_304、_400、_401、_403、_404、_405、_409、_412、_500 共 13 种状态码，对应源码中 couchdb.go#L64-L78 的 httpdStatusCodes 结构体。

httpd 统计

指标前缀	含义
`httpd_clients_requesting_changes`	持续监听 `_changes` 的客户端数量
`httpd_temporary_view_reads`	临时视图读取次数
`httpd_requests`	HTTP 请求总数
`httpd_bulk_requests`	bulk 批量请求次数
`httpd_view_reads`	视图读取次数

字段后缀语义

每个指标项根据统计端点中携带的数据维度，生成对应的字段后缀。这一逻辑由 couchdb.go#L255-L277 的 generateFields 函数实现，其遵循"哪个维度非空就产出哪个字段"的原则：

后缀	含义
`_value`	当前值（CouchDB 2.x 采用，表示计数器当前数值）
`_current`	当前值（CouchDB 1.x 语义）
`_sum`	统计窗口内累计和
`_mean`	平均值
`_stddev`	标准差
`_min`	最小值
`_max`	最大值

例如 httpd_request_methods_get 在 1.x 下会展开为 httpd_request_methods_get_current、_sum、_mean、_stddev、_min、_max 等字段；在 2.x 下则主要输出 httpd_request_methods_get_value。所有值为 float64，源码中的 metaData 结构使用 *float64 指针类型以区分"数值为 0"与"字段缺失"（couchdb.go#L27-L41）。

Tags 标签

插件为每条指标附加单一标签：

server：该条数据来源的 CouchDB stats 端点完整 URL（即 hosts 数组中的元素）。

标签生成逻辑见 couchdb.go#L248-L251。由于该标签是完整的端点 URL（含 http:// 前缀），多主机采集时天然可按 server 维度区分数据，也意味着同一个 CouchDB 实例的不同端点会形成不同的 series。若后续需要对 server 标签做规范化处理，可配合全局配置中的 tagrename 等能力。

CouchDB 1.x 与 2.x 版本差异的自动适配

CouchDB 在 2.0 中对 _stats 端点的响应结构进行了调整，主要体现在：

1.x：统计值直接以 current、sum、mean、stddev、min、max 六个字段平铺在每个统计项下，且 httpd 相关统计位于顶层 httpd_request_methods、httpd_status_codes 节点。
2.x：统计项被收纳进 couchdb 节点内（如 couchdb.httpd_request_methods.GET.value），且大量统计改为单一 value 字段，端点路径也从 /_stats 变为 /_node/<node>/_stats。

插件通过一个巧妙的探测逻辑自动区分版本（couchdb.go#L182-L206）：判断 stats.Couchdb.HttpdRequestMethods.Get.Value 是否为非空——若 2.x 的 value 字段存在，则从 stats.Couchdb 下的嵌套节点重新取用 request_time、各请求方法、各状态码数据；否则沿用 1.x 的顶层结构。这一兼容设计让同一个插件配置可以同时覆盖混部场景下的新旧版本集群，仓库 dev/telegraf.conf 正是针对 couchdb16（1.x）与 couchdb22（2.x）双版本并存环境编写的验证配置。

示例输出

CouchDB 2.x 之后

couchdb,server=http://couchdb22:5984/_node/_local/_stats couchdb_auth_cache_hits_value=0,httpd_request_methods_delete_value=0,couchdb_auth_cache_misses_value=0,httpd_request_methods_get_value=42,httpd_status_codes_304_value=0,httpd_status_codes_400_value=0,httpd_request_methods_head_value=0,httpd_status_codes_201_value=0,couchdb_database_reads_value=0,httpd_request_methods_copy_value=0,couchdb_request_time_max=0,httpd_status_codes_200_value=42,httpd_status_codes_301_value=0,couchdb_open_os_files_value=2,httpd_request_methods_put_value=0,httpd_request_methods_post_value=0,httpd_status_codes_202_value=0,httpd_status_codes_403_value=0,httpd_status_codes_409_value=0,couchdb_database_writes_value=0,couchdb_request_time_min=0,httpd_status_codes_412_value=0,httpd_status_codes_500_value=0,httpd_status_codes_401_value=0,httpd_status_codes_404_value=0,httpd_status_codes_405_value=0,couchdb_open_databases_value=0 1536707179000000000

2.x 输出以 _value 后缀为主，request_time 仅有 min/max 维度，观测指标呈现"计数器"风格。

CouchDB 2.0 之前

couchdb,server=http://couchdb16:5984/_stats couchdb_request_time_sum=96,httpd_status_codes_200_sum=37,httpd_status_codes_200_min=0,httpd_requests_mean=0.005,httpd_requests_min=0,couchdb_request_time_stddev=3.833,couchdb_request_time_min=1,httpd_request_methods_get_stddev=0.073,httpd_request_methods_get_min=0,httpd_status_codes_200_mean=0.005,httpd_status_codes_200_max=1,httpd_requests_sum=37,couchdb_request_time_current=96,httpd_request_methods_get_sum=37,httpd_request_methods_get_mean=0.005,httpd_request_methods_get_max=1,httpd_status_codes_200_stddev=0.073,couchdb_request_time_mean=2.595,couchdb_request_time_max=25,httpd_request_methods_get_current=37,httpd_status_codes_200_current=37,httpd_requests_current=37,httpd_requests_stddev=0.073,httpd_requests_max=1 1536707179000000000

1.x 输出包含 _current、_sum、_mean、_stddev、_min、_max 全套维度，couchdb_request_time_mean、httpd_requests_mean 等均值/标准差字段可直接用于绘制延迟分布图表。两条示例均含精确到纳秒的时间戳（1536707179000000000）。

实战建议与监控场景

将 CouchDB 监控接入 Telegraf 的完整链路如下：

生成配置：执行 telegraf config --input-filter couchdb --output-filter <你的输出插件> 生成仅含该输入插件的配置文件（参见 docs/CONFIGURATION.md 的配置生成说明）。
填写端点：按集群实际节点填写 hosts，2.x 请使用 /_node/_local/_stats 路径并确认账号权限可读该端点。
追加输出：例如配合 outputs.influxdb 写入时序库，或配合 outputs.file 输出到文件/标准输出联调。
常用告警维度：
- httpd_status_codes_500_value / _sum 突增 → 服务端错误；
- couchdb_auth_cache_hits_value 长期为 0 而 _misses 上涨 → 认证缓存配置可能存在问题；
- couchdb_open_os_files_value 接近系统文件描述符上限 → 存在文件句柄泄漏风险；
- couchdb_request_time_mean 持续走高 → CouchDB 内部处理延迟上升。