Prometheus 监控 CouchDB 全栈实战：从文档读写到集群复制的实时可观测性

Apache CouchDB 作为一款基于 HTTP API 的文档型 NoSQL 数据库，其请求吞吐量、响应状态码分布、活动任务、视图构建性能以及复制进度等指标，直接决定着应用的数据可用性与一致性。Prometheus 生态通过轻量级的 couchdb-exporter，将 CouchDB 内置的 _stats 和 _system 端点转化为标准 Prometheus 指标，让开发与运维团队能够以统一的栈来监控这个以 “JSON over HTTP” 闻名的数据库。本文将带你从监控用户创建到告警规则落地，一步步实现 CouchDB 的全维度可观测。

1. CouchDB 监控方案概述

CouchDB 3.x 提供了丰富的统计与系统端点，但均为 JSON 格式且需要身份认证。直接抓取需借助 json_exporter 转换，过程繁琐。社区有现成的专用导出器：

  • gesellix/couchdb-prometheus-exporter：Go 语言编写，连接 CouchDB 的 _stats 和 _node API，自动生成指标，支持 Basic Auth、TLS，单进程多实例。
  • signal/couchdb_exporter：Python 实现，功能类似，但较老且维护不活跃。

本文以 gesellix/couchdb-prometheus-exporter 为核心，因为它轻量、配置简单、指标命名清晰。

2. 创建 CouchDB 监控账号

为了安全，不要使用管理员账户，而是创建一个仅能读取统计信息的角色。

登录 CouchDB 管理界面（Fauxton）或通过 API 操作。

创建只读数据库 _users 的用户（需要通过管理员操作）：

首先确保 CouchDB 已启用认证（[chttpd] require_valid_user = true）。然后创建一个监控用户：

PUT /_node/_local/_config/admins/monitor
"StrongPassword"

（如果在配置文件中设置了管理员，则无需此步）

由于导出器只需要访问 /_stats 和 /_node 端点，而这些端点默认需要 _admin 角色。在 CouchDB 3.x 中，可以创建一个具有 _admin 角色的用户，或者更精细地利用 角色 控制：修改 [couch_peruser] 或使用 _security 对象。但最简便的方式是创建一个管理员用户，因为导出器内部使用的是 /_stats 这类需要服务器管理员权限的端点。在生产环境中，可创建普通用户并为其添加 _admin 角色：

PUT /_node/_local/_config/admins/monitor
"StrongPassword"

或者通过 HTTP 基本认证创建：

curl -X PUT http://admin:adminpassword@localhost:5984/_node/_local/_config/admins/monitor -d '"monitorpassword"'

之后导出器将使用 monitor:monitorpassword 连接。

如果 CouchDB 使用集群，请确保在所有节点上同步了管理员账号。

3. 部署 couchdb-prometheus-exporter

3.1 使用 Docker（推荐）
docker run -d \
  --name couchdb-exporter \
  -p 9984:9984 \
  -e COUCHDB_URL=http://monitor:monitorpassword@192.168.1.70:5984 \
  gesellix/couchdb-prometheus-exporter:latest

更多参数可通过环境变量设置，如 EXPORTER_LISTEN_ADDRESS=:9984。

3.2 二进制部署

从 GitHub releases 下载对应平台的二进制，然后设置环境变量运行：

export COUCHDB_URL=http://monitor:StrongPassword@localhost:5984
export EXPORTER_LISTEN_ADDRESS=:9984
./couchdb-prometheus-exporter

访问 http://localhost:9984/metrics 即可看到以 couchdb_ 开头的指标。

4. 配置 Prometheus 抓取

scrape_configs:
  - job_name: 'couchdb'
    scrape_interval: 30s
    static_configs:
      - targets:
          - '10.0.0.80:9984'
        labels:
          instance: 'couchdb-node1'
          env: 'production'

若监控多个节点，为每个节点启动一个 exporter 或使用导出器支持的多目标模式（通过 COUCHDB_URL 指向集群任一节点，但推荐每节点一个实例以获得节点级指标）。

5. 核心监控指标解读与 PromQL

CouchDB Prometheus Exporter 暴露的指标大致分为以下几类：

分类 关键指标 含义 PromQL 示例
请求统计 couchdb_httpd_requests_total（带 method、code 标签） HTTP 请求计数 `rate(couchdb_httpd_requests_total{code=~"4…
请求耗时 couchdb_httpd_request_duration_seconds_sum / _count 请求累计耗时与次数 平均延迟：rate(couchdb_httpd_request_duration_seconds_sum[5m]) / rate(couchdb_httpd_request_duration_seconds_count[5m])
数据库读写 couchdb_database_reads_total、couchdb_database_writes_total 数据库读写操作计数 rate(couchdb_database_reads_total[5m]) / rate(couchdb_database_writes_total[5m])
活动任务 couchdb_active_tasks（带 type 标签） 当前活动任务数量（replication, indexer, view_compaction 等） 直接查询，或过滤 type=“replication”
复制状态 couchdb_replicator_jobs_total（由活动任务细分） 复制任务总数 结合活动任务判断复制是否卡住
视图/搜索 couchdb_view_reads_total、couchdb_view_updates_total 等 视图读取与更新次数 可用于观察 map-reduce 视图负载
HTTP 连接 couchdb_httpd_connections 当前打开的 HTTP 连接数 高连接数可能导致资源耗尽
认证请求 couchdb_httpd_authentication_requests_total（若端点暴露） 认证尝试次数 监控暴力破解
内存/资源 结合 node_exporter 监控 Erlang VM 内存（CouchDB 不直接暴露内存指标） 系统级监控 CPU、内存 用 node_exporter 补充

实际指标名称可能因版本略有不同，请访问 /metrics 确认。例如 couchdb_httpd_status_codes 等。常见的标签有 method、code、database、type。

重要 PromQL 示例：

  • 5xx 错误率：sum(rate(couchdb_httpd_requests_total{code=~"5.."}[5m])) by (instance)
  • 数据库写入 QPS：rate(couchdb_database_writes_total[1m])
  • 视图构建任务积压：couchdb_active_tasks{type="indexer"} 持续 > 0 可能表示索引构建跟不上。

6. Grafana 仪表盘推荐

目前社区没有统一的 CouchDB 仪表盘 ID，但可根据指标自行构建面板，或导入通用 JSON 仪表板。以下是常用做法：

  • 使用 ID 11106 （CouchDB Dashboard）：社区有人制作了基于 Prometheus 的 CouchDB 面板，包含 HTTP 状态码、延迟、数据库读写、活动任务、Erlang VM 等。可直接导入，需确保指标名称匹配（可能需要微调）。
  • 自建面板：用 Time Series 面板展示请求速率，Stat 面板展示错误率，Table 面板展示活动任务。

推荐使用 Dashboard ID 11106 作为起点，若不匹配请基于 /metrics 中的实际指标名调整查询。

7. 告警规则实战

groups:
  - name: couchdb_alerts
    rules:
      - alert: CouchDBNodeDown
        expr: up{job="couchdb"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "CouchDB 节点 {{ $labels.instance }} 不可达"

      - alert: CouchDBHigh5xxRate
        expr: rate(couchdb_httpd_requests_total{code=~"5.."}[5m]) > 0.05
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "CouchDB 返回 5xx 错误的速率过高"

      - alert: CouchDBHighRequestLatency
        expr: rate(couchdb_httpd_request_duration_seconds_sum[5m]) / rate(couchdb_httpd_request_duration_seconds_count[5m]) > 1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "CouchDB 平均请求延迟超过 1 秒"

      - alert: CouchDBReplicationBacklog
        expr: couchdb_active_tasks{type="replication"} > 0
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: "CouchDB 复制任务长时间未完成"

      - alert: CouchDBHighConnections
        expr: couchdb_httpd_connections > 500
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "CouchDB HTTP 连接数超过 500"

      - alert: CouchDBViewBuildingBacklog
        expr: couchdb_active_tasks{type="indexer"} > 10
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "CouchDB 索引构建任务积压"

根据实际环境，可增加认证失败率、磁盘空间（结合 node_exporter）等告警。

8. 进阶：监控集群、安全与性能

8.1 监控 CouchDB 集群

集群中的每个节点都独立暴露 /metrics。建议为每个节点部署一个 exporter，并在 Prometheus 中配置多个 target，同时打上 node_name 标签。这样可以分别观察各节点的负载、请求分布和复制状态。

8.2 启用 TLS 与认证

若 CouchDB 已启用 HTTPS，则 COUCHDB_URL 需使用 https:// 前缀，并可能需跳过证书验证（测试）或挂载自定义 CA。Exporter 支持 COUCHDB_SKIP_VERIFY=true 环境变量。

docker run -d \
  -e COUCHDB_URL=https://monitor:pass@node1:6984 \
  -e COUCHDB_SKIP_VERIFY=false \
  -v /etc/ssl/certs/couchdb-ca.crt:/etc/ssl/certs/ca-certificates.crt:ro \
  -p 9984:9984 gesellix/couchdb-prometheus-exporter
8.3 减少抓取开销

Exporter 每次抓取会调用 CouchDB 的 /_stats 和 /_node/_local 等 API，对 CouchDB 性能影响微乎其微。建议 scrape_interval 保持在 30~60 秒，避免过于频繁。

8.4 结合 Erlang 内部指标

CouchDB 运行在 Erlang VM 上，但上述导出器并不暴露 Erlang 进程、消息队列等细节。如需深入，可启用 CouchDB 的 /_system 端点（需管理员）并配合 json_exporter 抓取，或直接使用 Erlang 的 Prometheus 库。不过对于大多数生产环境，HTTP 层指标已经足够。

通过这套方案，CouchDB 的请求状态、延迟趋势、任务堆积等核心信息会以可视化图表的方式呈现在 Grafana 中，任何 API 异常、复制停滞或资源瓶颈都会在第一时间触发告警。配合前面已经落地的 Linux 主机监控，你就能从硬件到文档数据库，构建起一条无死角的全栈可观测链。

# prometheus # couchdb
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

一个 API 入口调用多个大模型：AiiOnly客户端 + CC Switch 打通 Codex AI编程流程

avatar AI编程社区
cover

VSCode Claude Code + MiMo 中转免登录完整配置教程（解决原生登录弹窗 + 模型报错）

avatar AI编程社区
cover

从零开始做一个属于自己的 Skill（保姆级教程）

avatar AI编程社区