ClickStack による PostgreSQL ログの監視

要点OTel filelog receiver を使用して、PostgreSQL のサーバーログ (CSVフォーマット) を ClickStack に収集し、可視化します。デモデータセットとあらかじめ用意されたダッシュボードが含まれます。

既存のPostgreSQLとのインテグレーション

このセクションでは、ClickStack OTel collectorの設定を変更し、既存のPostgreSQL環境からClickStackにログを送信するよう構成する方法を説明します。既存環境を自分で構成する前にPostgreSQLログのインテグレーションを試したい場合は、“デモデータセット” セクションの事前構成済みセットアップとサンプルデータを使ってテストできます。

前提条件

稼働中の ClickStack インスタンス
既存の PostgreSQL 環境 (バージョン 9.6 以降)
PostgreSQL の設定ファイルを変更できる権限
ログファイルを保存するための十分なディスク容量

PostgreSQL のログ設定

PostgreSQL は複数のログ形式をサポートしています。OpenTelemetry で構造化された形でパースするには、一貫性があり、パースしやすい出力が得られる CSV format を推奨します。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 ログを標準の場所から読み取ります
複数行にまたがるログエントリを処理します (error は複数行に及ぶことがよくあります)
標準的な PostgreSQL ログのフィールドをすべて含む CSV フォーマットをパースします
元のログ時刻を保持するために timestamp を抽出します
HyperDX でフィルタリングできるように source: postgresql 属性を追加します
専用のパイプラインを介してログを ClickHouse exporter にルーティングします

カスタム設定では、新しい receiver とパイプラインのみを定義します
プロセッサ (memory_limiter、transform、batch) とエクスポーター (clickhouse) は、ベースの ClickStack 設定ですでに定義されているため、名前で参照するだけです
csv_parser operator は、標準的な PostgreSQL の CSV ログフィールドをすべて構造化された属性として抽出します
この設定では、collector の再起動時にログを再取り込みしないよう start_at: end を使用しています。テスト時は、過去のログをすぐに確認できるよう start_at: beginning に変更してください。
PostgreSQL のログ directory の場所に合わせて include path を調整してください

ClickStack でカスタム設定を読み込むように構成する

既存の ClickStack デプロイでカスタム collector 設定を有効にするには、次の作業が必要です。

カスタム設定ファイルを /etc/otelcol-contrib/custom.config.yaml にマウントします
環境変数 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml を設定します
collector が PostgreSQL のログを読み取れるように、PostgreSQL のログディレクトリをマウントします

オプション 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 Run (オールインワンイメージ)

docker run でオールインワンイメージを使用する場合:

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 にログインし、ログが取り込まれていることを確認します。

Searchビューに移動します
ログソースを Logs に設定します
PostgreSQL 固有のログを表示するには、source: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

テスト用の 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 の起動後、次の操作を行います。

HyperDX を開き、アカウントにログインします (先にアカウント作成が必要な場合があります)
Search ビューに移動し、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 にログが表示されない

実際に適用されている config に 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 Run (オールインワン イメージ)

​HyperDX でログを確認する

​デモデータセット

​サンプルデータセットをダウンロード

​テスト用の collector 設定を作成

​デモ設定で ClickStack を実行

​HyperDX でログを確認

​ダッシュボードと可視化

​ダッシュボード設定をする

​あらかじめ用意されたダッシュボードをインポートする

​ダッシュボードを表示する

​トラブルシューティング

​カスタム設定が読み込まれない

​HyperDX にログが表示されない

​次のステップ

​本番環境への移行

既存のPostgreSQLとのインテグレーション

PostgreSQL のログ設定

カスタム OTel collector 設定を作成する

ClickStack でカスタム設定を読み込むように構成する

オプション 2: Docker Run (オールインワンイメージ)

HyperDX でログを確認する

デモデータセット

サンプルデータセットをダウンロード

テスト用の collector 設定を作成

デモ設定で ClickStack を実行

HyperDX でログを確認

ダッシュボードと可視化

ダッシュボード設定をする

あらかじめ用意されたダッシュボードをインポートする

ダッシュボードを表示する

トラブルシューティング

カスタム設定が読み込まれない

HyperDX にログが表示されない

次のステップ

本番環境への移行