跳转到主要内容
简而言之使用 OTel filelog 接收器在 ClickStack 中收集并可视化 PostgreSQL 服务器日志 (CSV 格式) 。包含演示数据集和预置仪表盘。

​
与现有 PostgreSQL 集成

本节介绍如何通过修改 ClickStack OTel collector 配置，将现有的 PostgreSQL 实例配置为向 ClickStack 发送日志。 如果您想在配置自己现有的环境之前先测试 PostgreSQL 日志集成，可以在”演示数据集”部分使用我们预先配置的环境和示例数据进行测试。
前置条件
  • 正在运行的 ClickStack 实例
  • 已安装 PostgreSQL (9.6 或更高版本)
  • 具有修改 PostgreSQL 配置文件的权限
  • 有足够的磁盘空间存储日志文件
1

​
配置 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 中添加或修改以下设置：
# 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                 # 记录锁竞争情况
本指南使用 PostgreSQL 的 csvlog 格式，以便进行可靠的结构化解析。如果你使用的是 stderr 或 jsonlog 格式，则需要相应调整 OpenTelemetry Collector 的配置。
完成这些更改后，重启 PostgreSQL：
# 适用于 systemd
sudo systemctl restart postgresql

# 适用于 Docker
docker restart
检查日志是否正在写入：
# Linux 上的默认日志位置
tail -f /var/lib/postgresql/{version}/main/log/postgresql-*.log

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

​
创建自定义 OTel collector 配置

ClickStack 支持通过挂载自定义配置文件并设置环境变量来扩展基础 OpenTelemetry Collector 配置。该自定义配置会与 HyperDX 通过 OpAMP 管理的基础配置合并。创建一个名为 postgres-logs-monitoring.yaml 的文件，内容如下：
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 导出器
  • 您只需在自定义配置中定义新的接收器和管道
  • 处理器 (memory_limiter、transform、batch) 和导出器 (clickhouse) 已在基础 ClickStack 配置中定义，您只需按名称引用它们
  • csv_parser 操作符会将所有标准 PostgreSQL CSV 日志字段提取为结构化属性
  • 此配置使用 start_at: end，以避免在 collector 重启时重新摄取日志。测试时，可改为 start_at: beginning 以立即查看历史日志。
  • 调整 include 路径，使其与您的 PostgreSQL 日志目录位置一致
3

​
配置 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:
    # ... 现有配置 ...
    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 镜像：
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
确保 ClickStack collector 具备读取 PostgreSQL 日志文件所需的适当权限。在生产环境中，使用只读挂载 (:ro) ，并遵循最小权限原则。
4

​
在 HyperDX 中验证日志

配置完成后，登录 HyperDX，确认日志已正常流入：
  1. 前往搜索视图
  2. 将 source 设置为 Logs
  3. 使用 source:postgresql 过滤，以查看 PostgreSQL 特有的日志
  4. 你应该会看到结构化的日志条目，其中包含 user_name、database_name、error_severity、message、query 等字段。

​
演示数据集

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

​
下载样本数据集

下载样本日志文件：
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgresql.log
2

​
创建测试采集器配置

创建一个名为 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
3

​
使用演示配置运行 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
4

​
在 HyperDX 中验证日志

ClickStack 运行后：
  1. 打开 HyperDX 并登录您的账户 (您可能需要先创建一个账户)
  2. 导航到搜索视图，并将 source 设置为 Logs
  3. 将时间范围设置为 2025-11-09 00:00:00 - 2025-11-12 00:00:00
时区显示HyperDX 会以您浏览器的本地时区显示时间戳。演示数据的时间范围为 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC)。较大的时间范围可确保无论您身处何地都能看到演示日志。看到日志后，您可以将范围缩小到 24 小时，以获得更清晰的可视化效果。

​
仪表盘与可视化

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

​
仪表盘配置

2

​
导入预置仪表盘

  1. 打开 HyperDX 并进入 Dashboards 部分
  2. 点击右上角省略号菜单中的 Import Dashboard
  1. 上传 postgresql-logs-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 | 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 数据。
最后修改于 2026年6月10日