使用 ClickStack 监控 PostgreSQL 日志

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

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

# 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

创建自定义 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 日志目录位置一致

配置 ClickStack 以加载自定义配置

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

将自定义配置文件挂载到 /etc/otelcol-contrib/custom.config.yaml
设置环境变量 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
挂载 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) ，并遵循最小权限原则。

在 HyperDX 中验证日志

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

前往搜索视图
将 source 设置为 Logs
使用 source:postgresql 过滤，以查看 PostgreSQL 特有的日志
你应该会看到结构化的日志条目，其中包含 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

创建测试采集器配置

创建一个名为 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 运行后：

打开 HyperDX 并登录您的账户 (您可能需要先创建一个账户)
导航到搜索视图，并将 source 设置为 Logs
将时间范围设置为 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 日志的核心可视化内容。

仪表盘配置

导入预置仪表盘

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

上传 postgresql-logs-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 | 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 数据。

​与现有 PostgreSQL 集成

前置条件

​配置 PostgreSQL 日志

​创建自定义 OTel collector 配置

​配置 ClickStack 以加载自定义配置

选项 1：Docker Compose

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

​在 HyperDX 中验证日志

​演示数据集

​下载样本数据集

​创建测试采集器配置

​使用演示配置运行 ClickStack

​在 HyperDX 中验证日志

​仪表盘与可视化

​仪表盘配置

​导入预置仪表盘

​查看仪表盘

​故障排查

​自定义配置未加载

​HyperDX 中没有显示日志

​后续步骤

​投入生产环境

与现有 PostgreSQL 集成

配置 PostgreSQL 日志

创建自定义 OTel collector 配置

配置 ClickStack 以加载自定义配置

在 HyperDX 中验证日志

演示数据集

下载样本数据集

创建测试采集器配置

使用演示配置运行 ClickStack

在 HyperDX 中验证日志

仪表盘与可视化

仪表盘配置

导入预置仪表盘

查看仪表盘

故障排查

自定义配置未加载

HyperDX 中没有显示日志

后续步骤

投入生产环境