gesellix/couchdb-prometheus-exporter

CouchDB Prometheus Exporter

镜像概述和主要用途

CouchDB Prometheus Exporter 是用于 CouchDB 的指标导出工具，专为 Prometheus 设计。该工具从 CouchDB 的 /_stats 和 /_active_tasks 端点获取指标数据，并将其转换为 Prometheus 可消费的格式，便于监控 CouchDB 实例的性能和运行状态。

核心功能和特性

• 多端点指标采集：支持从 /_stats（系统统计）和 /_active_tasks（活跃任务）端点采集核心指标
• 灵活配置方式：支持通过环境变量、命令行参数和配置文件进行配置
• 安全认证支持：集成 TLS 加密和 Basic 认证，保护指标暴露端点
• 集群监控适配：兼容 CouchDB 2.x+ 集群，可配置从单节点获取集群整体指标
• 数据库存储监控：可选监控指定数据库或所有数据库的磁盘占用和数据大小
• 多部署模式支持：可作为独立二进制运行或通过 Docker 容器部署

使用场景和适用范围

• 生产环境 CouchDB 监控：适用于需要实时监控 CouchDB 性能指标（如请求量、响应时间、任务状态）的生产环境
• CouchDB 集群管理：支持对 CouchDB 2.x+ 集群进行统一监控，适配集群节点间的指标聚合
• 存储容量规划：通过数据库磁盘使用统计，辅助进行存储容量预警和规划
• Prometheus-Grafana 生态集成：无缝对接 Prometheus 和 Grafana，实现指标可视化和告警

详细的使用方法和配置说明

构建二进制（可选）

官方提供预构建版本，可从 https://github.com/gesellix/couchdb-prometheus-exporter/releases 获取。若需从源码构建，需先安装 Golang，然后执行：

shell
go install github.com/gesellix/couchdb-prometheus-exporter/v30@v30.4.2

二进制文件将安装至 GOBIN 目录（通常为 $HOME/go/bin），确保该目录在系统 PATH 中，可通过以下命令验证安装：

shell
couchdb-prometheus-exporter --help

运行方式

基本命令

通过 --help 查看所有配置选项及默认值：

shell
couchdb-prometheus-exporter --help

配置方式

支持三种配置方式，优先级：命令行参数 > 环境变量 > 配置文件。

1. 环境变量

格式：COUCHDB_<参数名>（参数名大写，. 替换为 _），例如：

shell
export COUCHDB_USERNAME=admin
export COUCHDB_PASSWORD=secret
export COUCHDB_URI=http://couchdb:5984

2. 命令行参数

格式：--<section>.<key> <value>，例如：

shell
couchdb-prometheus-exporter \
  --couchdb.username admin \
  --couchdb.password secret \
  --couchdb.uri http://couchdb:5984

3. 配置文件

支持 "properties" 格式配置文件，通过 --config 指定路径，例如 config.ini：

properties
# config.ini
couchdb.username=admin
couchdb.password=secret
couchdb.uri=http://couchdb:5984
databases=db-1,db-2  # 监控指定数据库的磁盘使用

启动命令：

shell
couchdb-prometheus-exporter --config=config.ini

TLS 和 Basic 认证配置

通过 --web.config 参数启用 TLS 和/或 Basic 认证，需指定 YAML 配置文件，例如 web-config.yaml：

yaml
# web-config.yaml
tls_server_config:
  cert_file: "path/to/server.crt"  # TLS 证书路径
  key_file: "path/to/server.key"   # TLS 私钥路径
basic_auth_users:
  alice: $2y$12$1DpfPeqF9HzHJt.EWswy1exHluGfbhnn3yXhR7Xes6m3WJqFg0Wby  # 加密后的密码
  bob: $2y$18$4VeFDzXIoPHKnKTU3O3GH.N.vZu06CVqczYZ8WvfzrddFU6tGqjR.

启动命令：

shell
couchdb-prometheus-exporter --config=config.ini --web.config=web-config.yaml

密码需通过 bcrypt 加密，可使用工具生成（如 htpasswd -nBC 10 ""）。

Docker 容器部署

基本运行命令

shell
docker run --rm -p 9984:9984 \
  gesellix/couchdb-prometheus-exporter \
  --couchdb.uri=http://couchdb:5984 \
  --couchdb.username=admin \
  --couchdb.password=secret

注意：容器内无法使用 localhost 访问宿主机服务，需使用宿主机 IP 或可解析的域名。

Docker Compose 示例

创建 docker-compose.yml：

yaml
version: '3'
services:
  couchdb-exporter:
    image: gesellix/couchdb-prometheus-exporter
    ports:
      - "9984:9984"
    environment:
      - COUCHDB_USERNAME=admin
      - COUCHDB_PASSWORD=secret
      - COUCHDB_URI=http://couchdb:5984
      - DATABASES=_all_dbs  # 监控所有数据库
    depends_on:
      - couchdb
  couchdb:
    image: couchdb:3.3
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=secret
    ports:
      - "5984:5984"

启动：

shell
docker-compose up -d

Docker Swarm/Stack 示例

创建 docker-stack.yml：

yaml
version: '3.8'
services:
  couchdb-exporter:
    image: gesellix/couchdb-prometheus-exporter
    ports:
      - "9984:9984"
    command:
      - --couchdb.uri=http://couchdb:5984
      - --couchdb.username=admin
      - --couchdb.password=secret
      - --databases=_all_dbs
    deploy:
      replicas: 1
  couchdb:
    image: couchdb:3.3
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=secret
    ports:
      - "5984:5984"
    deploy:
      replicas: 3  # 模拟 CouchDB 集群

部署：

shell
docker swarm init
docker stack deploy --compose-file docker-stack.yml couchdb-monitor

CouchDB 2+ 集群配置

对于 CouchDB 2.x+ 集群，需配置管理员凭证以获取集群指标：

shell
couchdb-prometheus-exporter \
  --couchdb.uri=http://couchdb-node-1:5984 \
  --couchdb.username=admin \
  --couchdb.password=secret

若需仅采集单个节点的本地指标，启用 --scrape.localonly：

shell
couchdb-prometheus-exporter \
  --couchdb.uri=http://couchdb-node-1:5984 \
  --couchdb.username=admin \
  --couchdb.password=secret \
  --scrape.localonly=true

数据库磁盘使用监控

指定需监控的数据库（逗号分隔）：

shell
couchdb-prometheus-exporter \
  --couchdb.uri=http://couchdb:5984 \
  --couchdb.username=admin \
  --couchdb.password=secret \
  --databases=db-1,db-2  # 监控 db-1 和 db-2

监控所有数据库，使用 _all_dbs：

shell
couchdb-prometheus-exporter \
  --couchdb.uri=http://couchdb:5984 \
  --couchdb.username=admin \
  --couchdb.password=secret \
  --databases=_all_dbs

指标概述

导出的指标详情可参考项目中的 https://github.com/gesellix/couchdb-prometheus-exporter/blob/master/README_metrics.md%EF%BC%8C%E6%B6%B5%E7%9B%96%E4%BB%A5%E4%B8%8B%E7%B1%BB%E5%88%AB%EF%BC%9A

• CouchDB 系统指标（请求数、响应时间、活跃任务等）
• 数据库指标（文档数、数据大小、磁盘占用等）
• 集群指标（节点状态、复制延迟等）

完整监控示例

Prometheus + Grafana 监控栈

参考 Monitoring CouchDB with Prometheus, Grafana and Docker 指南，或使用项目提供的示例栈（包含 CouchDB、Exporter、Prometheus、Grafana）：

shell
cd examples/grafana
docker swarm init
docker stack deploy --compose-file docker-traefik-stack.yml example

访问 Grafana（默认地址 http://localhost:3000），导入示例仪表盘即可查看监控数据。

配置参数说明