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 实例配置为向 ClickStack 发送日志。

如果您想在配置自己现有的环境之前先测试 PostgreSQL 日志集成，可以在"演示数据集"部分使用我们预先配置的环境和示例数据进行测试。

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

配置 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 中添加或修改以下设置：

# Required for CSV logging
logging_collector = on
log_destination = 'csvlog'

# Recommended: Connection logging
log_connections = on
log_disconnections = on

# Optional: Tune based on your monitoring needs
#log_min_duration_statement = 1000  # Log queries taking more than 1 second
#log_statement = 'ddl'               # Log DDL statements (CREATE, ALTER, DROP)
#log_checkpoints = on                # Log checkpoint activity
#log_lock_waits = on                 # Log lock contention

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

# For systemd
sudo systemctl restart postgresql

# For Docker
docker restart

检查日志是否正在写入：

# Default log location on Linux
tail -f /var/lib/postgresql/{version}/main/log/postgresql-*.log

# macOS Homebrew
tail -f /usr/local/var/postgres/log/postgresql-*.log

创建自定义 OTel collector 配置

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

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

receivers:
  filelog/postgres:
    include:
      - /var/lib/postgresql/*/main/log/postgresql-*.csv # Adjust to match your PostgreSQL installation
    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 导出器

配置 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 部署配置：

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/lib/postgresql:/var/lib/postgresql:ro
      # ... other volumes ...
选项 2：Docker 运行 (All-in-One 镜像)

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

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

在 HyperDX 中验证日志

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

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

演示数据集

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

下载样本数据集

下载样本日志文件：

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgresql.log

创建测试 collector 配置

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

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

使用演示配置运行 ClickStack

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

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

在 HyperDX 中验证日志

ClickStack 运行后：

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

仪表盘与可视化

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

下载仪表盘配置

下载仪表盘配置文件。

导入预置仪表盘

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

查看仪表盘

仪表盘创建后，其中的所有可视化都已预先配置完成：

日志仪表盘

故障排查

自定义配置未加载

请确认环境变量已正确设置：

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

检查自定义配置文件是否已挂载且可读取：

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

HyperDX 中没有显示日志

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

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

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

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

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

docker exec <container> cat /tmp/postgres-demo/postgresql.log | wc -l

后续步骤

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

面向生产环境

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

Navigation