借助 ClickStack 监控 PostgreSQL 指标

借助 ClickStack 监控 PostgreSQL 指标

简而言之

使用 OTel PostgreSQL 接收器在 ClickStack 中监控 PostgreSQL 性能指标。包含演示数据集和预置仪表板。

​

与现有 PostgreSQL 集成

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

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

前置条件

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

1. ​

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

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

   GRANT pg_monitor TO your_monitoring_user;
   
2. ​

   创建自定义 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]
   

   tls: insecure: true 设置会禁用 SSL 验证，仅适用于开发/测试环境。对于启用了 SSL 的生产环境 PostgreSQL，请删除此行或正确配置证书。

3. ​

   使用自定义配置部署 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
   
4. ​

   验证指标采集

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

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

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

​

演示数据集

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

仅包含数据库级指标

此演示数据集仅包含数据库级指标，以保持样本数据足够轻量。在监控真实的 PostgreSQL 数据库时，表和索引指标会自动采集。

1. ​

   下载样本指标数据集

   下载预先生成的指标文件 (包含 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) - 罕见死锁
2. ​

   启动 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 完全启动。

3. ​

   将指标加载到 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"
   
4. ​

   在 HyperDX 中验证指标

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

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

   时区显示

   HyperDX 会按浏览器的本地时区显示时间戳。演示数据覆盖 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC)。请将时间范围设置为 2025-11-09 00:00:00 - 2025-11-12 00:00:00，以确保无论你身处何地都能看到演示指标。看到指标后，你可以将范围缩小到 24 小时，以获得更清晰的可视化效果。

​

仪表盘与可视化

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

1. ​

   仪表盘配置

2. ​

   导入预置仪表盘

   1. 打开 HyperDX 并进入仪表盘部分
   2. 点击右上角省略号菜单中的 Import Dashboard

   3. 上传 postgres-metrics-dashboard.json 文件，然后点击 Finish Import
3. ​

   查看仪表盘

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

   对于演示数据集，请将时间范围设置为 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC) (请根据你的本地时区进行调整) 。默认情况下，导入的仪表盘不会预设时间范围。

​

故障排查

​

自定义配置未生效

请确认环境变量已设置：

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 数据。