> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.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 `filelog` 接收器在 ClickStack 中收集并可视化 PostgreSQL 服务器日志 (CSV 格式) 。包含演示数据集和预置仪表盘。
</Info>

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

本节介绍如何通过修改 ClickStack OTel collector 配置，将现有的 PostgreSQL 实例配置为向 ClickStack 发送日志。

如果您想在配置自己现有的环境之前先测试 PostgreSQL 日志集成，可以在["演示数据集"](/zh/clickstack/integration-examples/postgres-logs#demo-dataset)部分使用我们预先配置的环境和示例数据进行测试。

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

* 正在运行的 ClickStack 实例
* 已安装 PostgreSQL (9.6 或更高版本)
* 具有修改 PostgreSQL 配置文件的权限
* 有足够的磁盘空间存储日志文件

<Steps>
  <Step>
    #### 配置 PostgreSQL 日志

    PostgreSQL 支持多种日志格式。为了便于使用 OpenTelemetry 进行结构化解析，我们建议使用 CSV 格式，因为它能提供一致且易于解析的输出。

    `postgresql.conf` 文件通常位于：

    * **Linux (apt/yum)**: `/etc/postgresql/{version}/main/postgresql.conf`
    * **macOS (Homebrew)**: `/usr/local/var/postgres/postgresql.conf` 或 `/opt/homebrew/var/postgres/postgresql.conf`
    * **Docker**: 配置通常通过环境变量或挂载的配置文件来设置

    在 `postgresql.conf` 中添加或修改以下设置：

    ```conf theme={null}
    # CSV 日志所需配置
    logging_collector = on
    log_destination = 'csvlog'

    # 推荐：连接日志
    log_connections = on
    log_disconnections = on

    # 可选：根据监控需求进行调整
    #log_min_duration_statement = 1000  # 记录耗时超过 1 秒的查询
    #log_statement = 'ddl'               # 记录 DDL 语句（CREATE、ALTER、DROP）
    #log_checkpoints = on                # 记录检查点活动
    #log_lock_waits = on                 # 记录锁竞争情况
    ```

    <Note>
      本指南使用 PostgreSQL 的 `csvlog` 格式，以便进行可靠的结构化解析。如果你使用的是 `stderr` 或 `jsonlog` 格式，则需要相应调整 OpenTelemetry Collector 的配置。
    </Note>

    完成这些更改后，重启 PostgreSQL：

    ```bash theme={null}
    # 适用于 systemd
    sudo systemctl restart postgresql

    # 适用于 Docker
    docker restart 
    ```

    检查日志是否正在写入：

    ```bash theme={null}
    # Linux 上的默认日志位置
    tail -f /var/lib/postgresql/{version}/main/log/postgresql-*.log

    # macOS Homebrew
    tail -f /usr/local/var/postgres/log/postgresql-*.log
    ```
  </Step>

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

    ClickStack 支持通过挂载自定义配置文件并设置环境变量来扩展基础 OpenTelemetry Collector 配置。该自定义配置会与 HyperDX 通过 OpAMP 管理的基础配置合并。

    创建一个名为 `postgres-logs-monitoring.yaml` 的文件，内容如下：

    ```yaml theme={null}
    receivers:
      filelog/postgres:
        include:
          - /var/lib/postgresql/*/main/log/postgresql-*.csv # 请根据您的 PostgreSQL 实际安装路径进行调整
        start_at: end
        multiline:
          line_start_pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
        operators:
          - type: csv_parser
            parse_from: body
            parse_to: attributes
            header: 'log_time,user_name,database_name,process_id,connection_from,session_id,session_line_num,command_tag,session_start_time,virtual_transaction_id,transaction_id,error_severity,sql_state_code,message,detail,hint,internal_query,internal_query_pos,context,query,query_pos,location,application_name,backend_type,leader_pid,query_id'
            lazy_quotes: true
            
          - type: time_parser
            parse_from: attributes.log_time
            layout: '%Y-%m-%d %H:%M:%S.%L %Z'
          
          - type: add
            field: attributes.source
            value: "postgresql"
          
          - type: add
            field: resource["service.name"]
            value: "postgresql-production"

    service:
      pipelines:
        logs/postgres:
          receivers: [filelog/postgres]
          processors:
            - memory_limiter
            - transform
            - batch
          exporters:
            - clickhouse
    ```

    此配置会：

    * 从 PostgreSQL CSV 日志的标准位置读取日志
    * 处理多行日志条目 (错误通常会跨越多行)
    * 解析包含所有标准 PostgreSQL 日志字段的 CSV 格式
    * 提取时间戳，以保留原始日志时间
    * 添加 `source: postgresql` 属性，以便在 HyperDX 中过滤
    * 通过专用管道将日志发送到 ClickHouse 导出器

    <Note>
      - 您只需在自定义配置中定义新的接收器和管道
      - 处理器 (`memory_limiter`、`transform`、`batch`) 和导出器 (`clickhouse`) 已在基础 ClickStack 配置中定义，您只需按名称引用它们
      - `csv_parser` 操作符会将所有标准 PostgreSQL CSV 日志字段提取为结构化属性
      - 此配置使用 `start_at: end`，以避免在 collector 重启时重新摄取日志。测试时，可改为 `start_at: beginning` 以立即查看历史日志。
      - 调整 `include` 路径，使其与您的 PostgreSQL 日志目录位置一致
    </Note>
  </Step>

  <Step>
    #### 配置 ClickStack 以加载自定义配置

    要在现有的 ClickStack 部署中启用自定义 collector 配置，您必须：

    1. 将自定义配置文件挂载到 `/etc/otelcol-contrib/custom.config.yaml`
    2. 设置环境变量 `CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml`
    3. 挂载 PostgreSQL 日志目录，以便 collector 能够读取其中的日志

    ##### 选项 1：Docker Compose

    更新 ClickStack 部署配置：

    ```yaml theme={null}
    services:
      clickstack:
        # ... 现有配置 ...
        environment:
          - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
          # ... 其他环境变量 ...
        volumes:
          - ./postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
          - /var/lib/postgresql:/var/lib/postgresql:ro
          # ... 其他挂载卷 ...
    ```

    ##### 选项 2：Docker 运行 (All-in-One 镜像)

    如果你使用的是通过 docker run 启动的 All-in-One 镜像：

    ```bash theme={null}
    docker run --name clickstack \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
      -v "$(pwd)/postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
      -v /var/lib/postgresql:/var/lib/postgresql:ro \
      clickhouse/clickstack-all-in-one:latest
    ```

    <Note>
      确保 ClickStack collector 具备读取 PostgreSQL 日志文件所需的适当权限。在生产环境中，使用只读挂载 (`:ro`) ，并遵循最小权限原则。
    </Note>
  </Step>

  <Step>
    #### 在 HyperDX 中验证日志

    配置完成后，登录 HyperDX，确认日志已正常流入：

    1. 前往搜索视图
    2. 将 source 设置为 Logs
    3. 使用 `source:postgresql` 过滤，以查看 PostgreSQL 特有的日志
    4. 你应该会看到结构化的日志条目，其中包含 `user_name`、`database_name`、`error_severity`、`message`、`query` 等字段。

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-logs-search-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=87ab35375b03f510dedf4c94fa6169e6" alt="日志搜索视图" width="3808" height="1926" data-path="images/clickstack/postgres/postgres-logs-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-log-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=f67799801fd754bb381c4a88ba259b1a" alt="日志视图" width="3808" height="1926" data-path="images/clickstack/postgres/postgres-log-view.png" />
  </Step>
</Steps>

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

对于想在配置生产系统之前先测试 PostgreSQL 日志集成的用户，我们提供了一个预生成的 PostgreSQL 日志样本数据集，其中包含贴近真实场景的日志模式。

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

    下载样本日志文件：

    ```bash theme={null}
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgresql.log
    ```
  </Step>

  <Step>
    #### 创建测试采集器配置

    创建一个名为 `postgres-logs-demo.yaml` 的文件，内容如下：

    ```yaml theme={null}
    cat > postgres-logs-demo.yaml << 'EOF'
    receivers:
      filelog/postgres:
        include:
          - /tmp/postgres-demo/postgresql.log
        start_at: beginning  # 为演示数据从头开始读取
        multiline:
          line_start_pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
        operators:
          - type: csv_parser
            parse_from: body
            parse_to: attributes
            header: 'log_time,user_name,database_name,process_id,connection_from,session_id,session_line_num,command_tag,session_start_time,virtual_transaction_id,transaction_id,error_severity,sql_state_code,message,detail,hint,internal_query,internal_query_pos,context,query,query_pos,location,application_name,backend_type,leader_pid,query_id'
            lazy_quotes: true
            
          - type: time_parser
            parse_from: attributes.log_time
            layout: '%Y-%m-%d %H:%M:%S.%L %Z'
          
          - type: add
            field: attributes.source
            value: "postgresql-demo"
          
          - type: add
            field: resource["service.name"]
            value: "postgresql-demo"

    service:
      pipelines:
        logs/postgres-demo:
          receivers: [filelog/postgres]
          processors:
            - memory_limiter
            - transform
            - batch
          exporters:
            - clickhouse
    EOF
    ```
  </Step>

  <Step>
    #### 使用演示配置运行 ClickStack

    使用演示日志和配置运行 ClickStack：

    ```bash theme={null}
    docker run --name clickstack-demo \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
      -v "$(pwd)/postgres-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
      -v "$(pwd)/postgresql.log:/tmp/postgres-demo/postgresql.log:ro" \
      clickhouse/clickstack-all-in-one:latest
    ```
  </Step>

  <Step>
    #### 在 HyperDX 中验证日志

    ClickStack 运行后：

    1. 打开 [HyperDX](http://localhost:8080/) 并登录您的账户 (您可能需要先创建一个账户)
    2. 导航到搜索视图，并将 source 设置为 `Logs`
    3. 将时间范围设置为 **2025-11-09 00:00:00 - 2025-11-12 00:00:00**

    <Info>
      **时区显示**

      HyperDX 会以您浏览器的本地时区显示时间戳。演示数据的时间范围为 **2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC)**。较大的时间范围可确保无论您身处何地都能看到演示日志。看到日志后，您可以将范围缩小到 24 小时，以获得更清晰的可视化效果。
    </Info>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-logs-search-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=87ab35375b03f510dedf4c94fa6169e6" alt="日志搜索视图" width="3808" height="1926" data-path="images/clickstack/postgres/postgres-logs-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-log-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=f67799801fd754bb381c4a88ba259b1a" alt="日志视图" width="3808" height="1926" data-path="images/clickstack/postgres/postgres-log-view.png" />
  </Step>
</Steps>

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

为帮助你开始使用 ClickStack 监控 PostgreSQL，我们提供了用于查看 PostgreSQL 日志的核心可视化内容。

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

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

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

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/import-logs-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=124a9f7be58754836400e4f32ebbc47c" alt="完成导入" width="3808" height="1926" data-path="images/clickstack/postgres/import-logs-dashboard.png" />
  </Step>

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-logs-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=7a4ae98a5f93e2ee57257ae7a3c58a09" alt="日志仪表盘" width="3808" height="1926" data-path="images/clickstack/postgres/postgres-logs-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 | head -10
```

<div id="no-logs">
  ### HyperDX 中没有显示日志
</div>

检查生效的配置中是否包含你的 `filelog receiver`：

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog
```

检查 collector 的日志中是否有错误：

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

如果使用演示数据集，请确认日志文件可正常访问：

```bash theme={null}
docker exec <container> cat /tmp/postgres-demo/postgresql.log | wc -l
```

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

* 为关键事件 (连接故障、慢查询、错误激增) 设置[告警](/zh/clickstack/features/alerts)
* 将日志与 [PostgreSQL 指标](/zh/clickstack/integration-examples/postgres-metrics)关联，以实现全面的数据库监控
* 为应用程序特有的查询模式创建自定义仪表盘
* 配置 `log_min_duration_statement`，以识别超过您性能要求阈值的慢查询

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

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