ongres/prometheus-postgres-exporter

镜像概述

PostgreSQL Prometheus Exporter OCI镜像是一个遵循OCI（开放容器倡议）标准的容器化工具，旨在从PostgreSQL数据库实例中采集关键指标（如连接数、查询性能、锁状态、资源使用率等），并将其转换为Prometheus监控系统可识别的格式，通过HTTP端点暴露供Prometheus抓取。该镜像轻量、易配置，可无缝集成到基于Prometheus的监控体系中，适用于各类PostgreSQL部署环境（包括物理机、虚拟机及容器化环境）。

核心功能和特性

指标采集能力

• 覆盖PostgreSQL核心指标：包括连接状态（活跃连接数、空闲连接数、最大连接数）、查询性能（慢查询数量、查询执行时间分布）、事务状态（活跃事务数、已提交/回滚事务数）、锁信息（表锁、行锁数量及类型）、资源使用率（CPU/内存消耗、磁盘I/O）等。
• 支持自定义指标：通过配置文件扩展，可采集用户定义的业务或应用相关指标。

Prometheus兼容性

• 内置Prometheus标准端点：默认暴露/metrics HTTP端点，返回符合Prometheus文本格式的指标数据，支持Prometheus自动发现和抓取。
• 指标标签丰富：指标包含数据库名称、实例标识等标签，便于多实例监控和聚合分析。

配置灵活性

• 多方式配置：支持通过环境变量快速配置（适用于简单场景）或自定义配置文件（适用于复杂场景）。
• 连接串灵活定义：支持标准PostgreSQL连接串（postgresql://user:password@host:port/dbname）配置，兼容多种认证方式（密码、SSL等）。

轻量级与兼容性

• 精简镜像体积：基于Alpine或Distroless基础镜像，降低资源占用。
• 广泛版本支持：兼容PostgreSQL 9.6+及更高版本，适配主流数据库版本。

使用场景和适用范围

典型应用场景

• PostgreSQL数据库监控：实时跟踪数据库运行状态，如连接数异常、查询延迟升高、锁竞争等。
• 性能分析与优化：通过历史指标趋势分析数据库性能瓶颈，辅助优化索引、查询语句或资源配置。
• 告警规则配置：结合Prometheus Alertmanager，基于采集指标配置告警（如连接数超过阈值、事务回滚率异常等）。
• 容器化环境集成：在Kubernetes、Docker Swarm等容器编排平台中，作为Sidecar容器或独立Deployment部署，监控容器内PostgreSQL实例。

适用范围

• 开发/测试环境：快速搭建数据库监控，验证应用与数据库交互性能。
• 生产环境：7x24小时持续监控，保障数据库稳定性。
• 混合部署架构：同时支持物理机、虚拟机及容器化部署的PostgreSQL实例监控。

使用方法和配置说明

基本使用（Docker Run）

通过docker run命令快速启动 exporter，核心配置通过环境变量传递：

bash
docker run -d \
  --name postgres-exporter \
  -p 9187:9187 \  # 默认监听端口9187
  -e DATA_SOURCE_NAME="postgresql://user:password@postgres-host:5432/dbname?sslmode=disable" \  # PostgreSQL连接串
  -e LISTEN_PORT=9187 \  # 监听端口（可选，默认9187）
  -e LISTEN_ADDRESS="0.0.0.0" \  # 监听地址（可选，默认0.0.0.0）
  prometheuscommunity/postgres-exporter:latest

关键环境变量说明

Docker Compose 示例

在容器化应用中，可通过docker-compose.yml集成 exporter 与 PostgreSQL：

yaml
version: '3.8'
services:
  postgres:
    image: docker.xuanyuan.run/postgres:14
    environment:
      POSTGRES_USER: dbuser
      POSTGRES_PASSWORD: dbpass
      POSTGRES_DB: appdb
    ports:
      - "5432:5432"

  postgres-exporter:
    image: docker.xuanyuan.run/prometheuscommunity/postgres-exporter:latest
    ports:
      - "9187:9187"
    environment:
      DATA_SOURCE_NAME: "postgresql://dbuser:dbpass@postgres:5432/appdb?sslmode=disable"
    depends_on:
      - postgres

配置文件使用（高级场景）

对于复杂指标采集需求（如自定义指标、过滤特定指标等），可通过配置文件定义采集规则。配置文件为YAML格式，示例：

yaml
# postgres_exporter.yml
refresh_interval: 5s  # 指标采集间隔
metrics:
  - name: pg_custom_query_seconds
    help: "Duration of custom query execution"
    type: gauge
    query: "SELECT EXTRACT(EPOCH FROM NOW() - query_start) AS duration FROM pg_stat_activity WHERE state = 'active'"
    columns:
      - name: duration
        usage: "value"

启动容器时挂载配置文件：

bash
docker run -d \
  --name postgres-exporter \
  -p 9187:9187 \
  -e DATA_SOURCE_NAME="postgresql://user:password@postgres-host:5432/dbname?sslmode=disable" \
  -e PG_EXPORTER_CONFIG_FILE="/etc/postgres-exporter/postgres_exporter.yml" \
  -v ./postgres_exporter.yml:/etc/postgres-exporter/postgres_exporter.yml \
  docker.xuanyuan.run/prometheuscommunity/postgres-exporter:latest

验证指标暴露

启动后，通过访问 http://<exporter-ip>:9187/metrics 验证指标是否正常暴露，响应应包含以 pg_ 为前缀的Prometheus指标（如 pg_stat_database_numbackends、pg_locks_count 等）。

注意事项

• 权限配置：确保PostgreSQL用户具备足够权限（如pg_monitor角色），以访问pg_stat_*等系统视图。
• 连接安全性：生产环境中建议启用SSL（连接串添加sslmode=require），避免明文传输凭据。
• 资源限制：根据数据库规模调整exporter资源（CPU/内存），高并发场景建议适当提高采集间隔（默认5秒）。