> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 借助 ClickStack 监控 PostgreSQL 指标

> 借助 ClickStack 监控 PostgreSQL 指标

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **简而言之**

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

<div id="existing-postgres">
  ## 与现有 PostgreSQL 集成
</div>

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

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

<div id="prerequisites">
  ##### 前置条件
</div>

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

<Steps>
  <Step>
    #### 确保监控用户具有所需权限

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

    ```sql theme={null}
    GRANT pg_monitor TO your_monitoring_user;
    ```
  </Step>

  <Step>
    #### 创建自定义 OTel collector 配置

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

    创建 `postgres-metrics.yaml`：

    ```yaml theme={null}
    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]
    ```

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

  <Step>
    #### 使用自定义配置部署 ClickStack

    挂载你的自定义配置：

    ```bash theme={null}
    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
    ```
  </Step>

  <Step>
    #### 验证指标采集

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

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

    确认指标正常流入后，继续前往[仪表盘与可视化](#dashboards)部分导入预置仪表盘。
  </Step>
</Steps>

<div id="demo-dataset">
  ## 演示数据集
</div>

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

<Info>
  **仅包含数据库级指标**

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

<Steps>
  <Step>
    #### 下载样本指标数据集

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

    ```bash theme={null}
    # 下载 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) ** - 罕见死锁
  </Step>

  <Step>
    #### 启动 ClickStack

    启动一个 ClickStack 实例：

    ```bash theme={null}
    docker run -d --name clickstack-postgres-demo \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      clickhouse/clickstack-all-in-one:latest
    ```

    等待大约 30 秒，让 ClickStack 完全启动。
  </Step>

  <Step>
    #### 将指标加载到 ClickStack 中

    将指标直接加载到 ClickHouse：

    ```bash theme={null}
    # 加载 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"
    ```
  </Step>

  <Step>
    #### 在 HyperDX 中验证指标

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

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

    <Info>
      **时区显示**

      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 小时，以获得更清晰的可视化效果。
    </Info>
  </Step>
</Steps>

<div id="dashboards">
  ## 仪表盘与可视化
</div>

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

<Steps>
  <Step>
    #### <TrackedLink href={'/zh/examples/postgres-metrics-dashboard.json'} download="postgres-metrics-dashboard.json" eventName="docs.postgres_metrics_monitoring.dashboard_download">下载</TrackedLink>仪表盘配置
  </Step>

  <Step>
    #### 导入预置仪表盘

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/import-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=cdfe26f160c1c080b995c8451311241d" alt="导入仪表盘按钮" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/postgres/import-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=fcee3f840abd5b1990ce6bbd31ac4ce7" alt="完成导入对话框" width="3808" height="1910" data-path="images/clickstack/postgres/import-dashboard.png" />
  </Step>

  <Step>
    #### 查看仪表盘

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/postgres/postgres-metrics-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=37b260132de447de9dcea6411192a4aa" alt="PostgreSQL 指标仪表盘" width="3808" height="1910" data-path="images/clickstack/postgres/postgres-metrics-dashboard.png" />

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

<div id="troubleshooting">
  ## 故障排查
</div>

<div id="troubleshooting-not-loading">
  ### 自定义配置未生效
</div>

请确认环境变量已设置：

```bash theme={null}
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
```

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

```bash theme={null}
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
```

<div id="no-metrics">
  ### HyperDX 中没有显示任何指标
</div>

请确认 PostgreSQL 可访问：

```bash theme={null}
docker exec <clickstack-container> psql -h postgres-host -U otel_monitor -d postgres -c "SELECT 1"
```

查看 OTel collector 日志：

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i postgres
```

<div id="auth-errors">
  ### 身份验证错误
</div>

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

```bash theme={null}
docker exec <clickstack-container> printenv POSTGRES_PASSWORD
```

直接测试凭据：

```bash theme={null}
psql -h postgres-host -U otel_monitor -d postgres -c "SELECT version();"
```

<div id="next-steps">
  ## 后续步骤
</div>

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

<div id="going-to-production">
  ## 投入生产环境
</div>

本指南利用 ClickStack 内置的 OpenTelemetry Collector 实现快速设置。对于生产环境部署，我们建议运行您自己的 OTel Collector，并将数据发送到 ClickStack 的 OTLP 端点。有关生产环境配置，请参阅[发送 OpenTelemetry 数据](/zh/clickstack/ingesting-data/opentelemetry)。