PgBouncer Metrics Sidecar 镜像文档

镜像概述

该镜像为PgBouncer连接池提供Sidecar容器支持，专注于收集并暴露PgBouncer运行指标。作为辅助容器，它与PgBouncer实例协同工作，将关键性能指标（如连接数、查询量等）转换为监控系统兼容格式（如Prometheus），支持用户实时监控PgBouncer状态与性能。

核心功能与特性

• 指标采集：自动采集PgBouncer核心指标，包括活跃连接数、空闲连接数、等待连接数、查询总数、连接请求数等
• 标准暴露：通过HTTP接口以Prometheus兼容格式暴露指标，支持主流监控系统集成
• 轻量设计：容器体积小，资源占用低，适合作为Sidecar在容器化环境中部署
• 灵活配置：支持通过环境变量自定义PgBouncer连接参数、指标暴露端口及采集频率

使用场景与适用范围

• 容器化部署PgBouncer的生产环境，需监控连接池性能的场景
• Kubernetes集群中与PgBouncer Pod配合的Sidecar部署模式
• Docker Compose多容器应用中集成PgBouncer监控能力
• 需要将PgBouncer指标接入Prometheus+Grafana监控体系的场景

使用方法与配置说明

基本部署方式

Docker Run 部署示例

需确保Sidecar与PgBouncer容器在同一网络环境中，以便正常通信：

bash
# 创建专用网络
docker network create pgbouncer-monitor-net

# 启动PgBouncer容器（示例）
docker run -d \
  --name pgbouncer \
  --network pgbouncer-monitor-net \
  -v /path/to/pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini \
  pgbouncer/pgbouncer

# 启动Metrics Sidecar容器
docker run -d \
  --name pgbouncer-metrics \
  --network pgbouncer-monitor-net \
  -e PGBOUNCER_HOST=pgbouncer \
  -e PGBOUNCER_PORT=6432 \
  -e PGBOUNCER_USER=pgbouncer_admin \
  -e PGBOUNCER_PASSWORD=secure_password \
  -e METRICS_PORT=9127 \
  pgbouncer-metrics-sidecar

Docker Compose 配置示例

yaml
version: '3.8'

services:
  pgbouncer:
    image: pgbouncer/pgbouncer
    volumes:
      - ./pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini
      - ./userlist.txt:/etc/pgbouncer/userlist.txt
    networks:
      - pgbouncer-net
    restart: unless-stopped

  pgbouncer-metrics:
    image: pgbouncer-metrics-sidecar
    environment:
      - PGBOUNCER_HOST=pgbouncer
      - PGBOUNCER_PORT=6432
      - PGBOUNCER_USER=pgbouncer_admin
      - PGBOUNCER_PASSWORD=secure_password
      - METRICS_PORT=9127
      - METRICS_PATH=/metrics
      - SCRAPE_INTERVAL=5
    ports:
      - "9127:9127"
    networks:
      - pgbouncer-net
    restart: unless-stopped

networks:
  pgbouncer-net:

配置参数说明

环境变量配置项

指标查看与集成

直接访问指标

部署后可通过以下URL直接查看指标： http://<sidecar-container-ip>:<METRICS_PORT><METRICS_PATH>

示例输出（Prometheus格式）：

pgbouncer_connections_active{database="postgres"} 8
pgbouncer_connections_idle{database="postgres"} 4
pgbouncer_connections_waiting{database="postgres"} 1
pgbouncer_queries_total{database="postgres"} 356
pgbouncer_connection_requests_total{database="postgres"} 120

Prometheus集成配置

在Prometheus配置文件中添加如下采集任务：

yaml
scrape_configs:
  - job_name: 'pgbouncer'
    static_configs:
      - targets: ['pgbouncer-metrics:9127']  # 替换为Sidecar容器的实际地址
    scrape_interval: 10s

配置后，Prometheus将定期采集指标，可结合Grafana创建可视化仪表盘监控PgBouncer运行状态。