借助 ClickStack 监控 PostgreSQL 指标

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

与现有 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]

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

使用自定义配置部署 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 并确认指标已开始流入：

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

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

演示数据集

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

时区显示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 指标的核心可视化内容。

下载仪表盘配置

。

导入预置仪表盘

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

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

查看仪表盘

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

对于演示数据集，请将时间范围设置为 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 数据。

​与现有 PostgreSQL 集成

前置条件

​演示数据集

​仪表盘与可视化

​故障排查

​自定义配置未生效

​HyperDX 中没有显示任何指标

​身份验证错误

​后续步骤

​进入生产环境

与现有 PostgreSQL 集成

演示数据集

仪表盘与可视化

故障排查

自定义配置未生效

HyperDX 中没有显示任何指标

身份验证错误

后续步骤

进入生产环境