Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

借助 ClickStack 监控 PostgreSQL 指标

View as MarkdownEdit this pageReport an issueSet up docs MCP

与现有 PostgreSQL 集成

本节介绍如何通过将 ClickStack OTel collector 配置为使用 PostgreSQL 接收器，使现有的 PostgreSQL 安装将指标发送到 ClickStack。

如果您想在配置自己的现有环境之前先测试 PostgreSQL 指标集成，可以在下一节中使用我们预先配置的演示数据集进行测试。

前置条件
  • 正在运行的 ClickStack 实例
  • 已安装 PostgreSQL (版本 9.6 或更高)
  • ClickStack 可通过网络访问 PostgreSQL (默认端口 5432)
  • 具有相应权限的 PostgreSQL 监控用户

确保监控用户具有所需权限

PostgreSQL 接收器需要一个对统计信息视图具有读取权限的用户。将 pg_monitor 角色授予你的监控用户：

GRANT pg_monitor TO your_monitoring_user;

创建自定义 OTel collector 配置

ClickStack 支持通过挂载自定义配置文件并设置环境变量，扩展基础 OpenTelemetry collector 配置。

创建 postgres-metrics.yaml：

receivers:
  postgresql:
    endpoint: postgres-host:5432
    transport: tcp
    username: otel_monitor
    password: ${env:POSTGRES_PASSWORD}
    databases:
      - postgres
      - your_application_db # 替换为你的实际数据库名称
    collection_interval: 30s
    tls:
      insecure: true

processors:
  resourcedetection:
    detectors: [env, system, docker]
    timeout: 5s
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  clickhouse:
    endpoint: tcp://localhost:9000
    database: default
    ttl: 96h

service:
  pipelines:
    metrics/postgres:
      receivers: [postgresql]
      processors: [resourcedetection, batch]
      exporters: [clickhouse]

使用自定义配置部署 ClickStack

挂载你的自定义配置：

docker run -d \
  --name clickstack-postgres \
  -p 8123:8123 -p 9000:9000 -p 4317:4317 -p 4318:4318 \
  -e HYPERDX_API_KEY=your-api-key \
  -e CLICKHOUSE_PASSWORD=your-clickhouse-password \
  -e POSTGRES_PASSWORD=secure_password_here \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/postgres-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  clickhouse/clickstack:latest

验证指标采集

配置完成后，登录 HyperDX 并确认指标已开始流入：

  1. 进入指标浏览器
  2. 搜索以 postgresql 开头的指标 (例如：postgresql.backends、postgresql.commits)
  3. 你应该会看到指标数据点按所配置的采集间隔持续出现

确认指标正常流入后，继续前往仪表盘与可视化部分导入预置仪表盘。

演示数据集

对于希望在配置生产系统之前先测试 PostgreSQL 指标集成的用户，我们提供了一个预先生成的数据集，其中包含逼真的 PostgreSQL 指标模式。

下载样本指标数据集

下载预先生成的指标文件 (包含 24 小时的 PostgreSQL 指标和逼真的变化模式)：

# 下载 Gauge 指标（连接数、数据库大小）
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-gauge.csv

# 下载 sum 指标（提交、回滚、操作）
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-sum.csv

该数据集包含以下逼真的模式：

  • 早晨连接高峰 (08:00) - 登录高峰期
  • 缓存性能问题 (11:00) - Blocks_read 激增
  • 应用程序缺陷 (14:00-14:30) - 回滚率飙升至 15%
  • 死锁事件 (14:15、16:30) - 罕见死锁

启动 ClickStack

启动一个 ClickStack 实例：

docker run -d --name clickstack-postgres-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

等待大约 30 秒，让 ClickStack 完全启动。

将指标加载到 ClickStack 中

将指标直接加载到 ClickHouse：

# 加载 Gauge 指标
cat postgres-metrics-gauge.csv | docker exec -i clickstack-postgres-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# 加载 sum 指标
cat postgres-metrics-sum.csv | docker exec -i clickstack-postgres-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

在 HyperDX 中验证指标

加载完成后，查看这些指标的最快方式是使用预置仪表盘。

继续前往 Dashboards and visualization 部分，导入仪表盘，一次查看多个 PostgreSQL 指标。

仪表盘与可视化

为帮助你快速开始使用 ClickStack 监控 PostgreSQL，我们提供了 PostgreSQL 指标的核心可视化内容。

下载仪表盘配置

下载仪表盘配置文件。

导入预置仪表盘

  1. 打开 HyperDX 并进入仪表盘部分
  2. 点击右上角省略号菜单中的 Import Dashboard
导入仪表盘按钮
  1. 上传 postgres-metrics-dashboard.json 文件，然后点击 Finish Import
完成导入对话框

查看仪表盘

仪表盘创建后，所有可视化内容都已预先配置好：

PostgreSQL 指标仪表盘

故障排查

自定义配置未生效

请确认环境变量已设置：

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

检查是否已挂载自定义配置文件：

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

HyperDX 中没有显示任何指标

请确认 PostgreSQL 可访问：

docker exec <clickstack-container> psql -h postgres-host -U otel_monitor -d postgres -c "SELECT 1"

查看 OTel collector 日志：

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i postgres

身份验证错误

确认密码是否已正确设置：

docker exec <clickstack-container> printenv POSTGRES_PASSWORD

直接测试凭据：

psql -h postgres-host -U otel_monitor -d postgres -c "SELECT version();"

后续步骤

  • 为关键阈值 (连接数限制、回滚率过高、缓存命中率过低) 配置告警
  • 启用 pg_stat_statements 扩展，以实现查询级监控
  • 复制 receiver 配置，并为其指定不同的端点和服务名称，以监控多个 PostgreSQL 实例

进入生产环境

本指南基于 ClickStack 内置的 OpenTelemetry Collector，可帮助您快速完成设置。对于生产环境部署，我们建议运行您自己的 OTel Collector，并将数据发送到 ClickStack 的 OTLP 端点。有关生产环境配置，请参阅发送 OpenTelemetry 数据。

Navigation