ClickStack を使用した PostgreSQL メトリクスの監視

TL;DR

このガイドでは、OpenTelemetry collector の PostgreSQL receiver を構成し、ClickStack で PostgreSQL のパフォーマンスメトリクスを監視する方法を説明します。次のことを学べます:

PostgreSQL メトリクスを収集するように OTel collector を構成する
カスタム設定を適用した ClickStack をデプロイする
事前構築済みのダッシュボードを使用して PostgreSQL のパフォーマンス（トランザクション、接続数、データベースサイズ、キャッシュヒット率）を可視化する

本番環境の PostgreSQL データベースを設定する前にインテグレーションをテストしたい場合のために、サンプルメトリクスを含むデモデータセットも利用できます。

所要時間: 10〜15 分

既存の PostgreSQL との統合

このセクションでは、PostgreSQL レシーバーを用いて ClickStack の OTel collector を構成し、既存の PostgreSQL 環境から ClickStack へメトリクスを送信できるようにする方法を説明します。

お使いの既存環境を構成する前に PostgreSQL メトリクス連携を試してみたい場合は、次のセクションの事前構成済みデモデータセットを使ってテストできます。

前提条件

ClickStack インスタンスが稼働していること
既存の PostgreSQL インストール（バージョン 9.6 以降）
ClickStack から PostgreSQL へのネットワークアクセス（デフォルトポート 5432）
適切な権限を持つ PostgreSQL 監視ユーザー

監視ユーザーに必要な権限が付与されていることを確認する

PostgreSQL receiver には、統計ビューへの読み取りアクセス権を持つユーザーが必要です。監視ユーザーに pg_monitor ロールを付与します:

GRANT pg_monitor TO your_monitoring_user;

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

ClickStack では、カスタム設定ファイルをマウントし、環境変数を設定することで、ベースの OpenTelemetry collector 設定を拡張できます。

postgres-metrics.yaml を作成します:

receivers:
  postgresql:
    endpoint: postgres-host:5432
    transport: tcp
    username: otel_monitor
    password: ${env:POSTGRES_PASSWORD}
    databases:
      - postgres
      - your_application_db # 実際のデータベース名に置き換えてください
    collection_interval: 30s
    tls:
      insecure: true

processors:
  resourcedetection:
    detectors: [env, system, docker]
    timeout: 5s
  batch:
    timeout: 10s
    send_batch_size: 1024

exporters:
  clickhouse:
    endpoint: tcp://localhost:9000
    database: default
    ttl: 96h

service:
  pipelines:
    metrics/postgres:
      receivers: [postgresql]
      processors: [resourcedetection, batch]
      exporters: [clickhouse]

注記

tls: insecure: true 設定は、開発／テスト用途で SSL 検証を無効化します。SSL が有効な本番環境の PostgreSQL では、この行を削除するか、適切な証明書を設定してください。

カスタム設定を用いて ClickStack をデプロイする

カスタム設定をマウントします:

docker run -d \
  --name clickstack-postgres \
  -p 8123:8123 -p 9000:9000 -p 4317:4317 -p 4318:4318 \
  -e HYPERDX_API_KEY=your-api-key \
  -e CLICKHOUSE_PASSWORD=your-clickhouse-password \
  -e POSTGRES_PASSWORD=secure_password_here \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/postgres-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  clickhouse/clickstack:latest

メトリクス収集を検証する

設定後、HyperDX にログインしてメトリクスが流れていることを確認します:

Metrics explorer に移動します
postgresql. で始まるメトリクスを検索します（例: postgresql.backends, postgresql.commits）
設定した収集間隔でメトリクスのデータポイントが表示されるはずです

メトリクスが流れていることを確認できたら、事前構築済みダッシュボードをインポートするために Dashboards and visualization セクションに進みます。

デモデータセット

本番システムを構成する前に PostgreSQL メトリクス連携をテストしたいユーザー向けに、現実的な PostgreSQL メトリクスパターンを含むあらかじめ生成されたデータセットを提供します。

データベースレベルのメトリクスのみ

このデモデータセットには、サンプルデータを軽量に保つためにデータベースレベルのメトリクスのみが含まれます。実際の PostgreSQL データベースを監視する場合、テーブルおよびインデックスのメトリクスは自動的に収集されます。

サンプルメトリクスデータセットをダウンロードする

あらかじめ生成されたメトリクスファイルをダウンロードします（現実的なパターンを持つ 24 時間分の PostgreSQL メトリクス）:

# ゲージメトリクスをダウンロード（接続数、データベースサイズ） \{#download-gauge-metrics-connections-database-size}
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-gauge.csv

# サムメトリクスをダウンロード（コミット、ロールバック、各種操作） \{#download-sum-metrics-commits-rollbacks-operations}
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-sum.csv

このデータセットには、次のような現実的なパターンが含まれます:

朝の接続スパイク (08:00) - ログインが集中
キャッシュ性能の問題 (11:00) - Blocks_read のスパイク
アプリケーションのバグ (14:00-14:30) - ロールバック率が 15% までスパイク
デッドロック発生 (14:15, 16:30) - まれなデッドロック

ClickStack を起動する

ClickStack インスタンスを起動します:

docker run -d --name clickstack-postgres-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

ClickStack が完全に起動するまで、約 30 秒待ちます。

メトリクスを ClickStack に読み込む

メトリクスを直接 ClickHouse に読み込みます:

# ゲージメトリクスを読み込む \{#load-gauge-metrics}
cat postgres-metrics-gauge.csv | docker exec -i clickstack-postgres-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# サムメトリクスを読み込む \{#load-sum-metrics}
cat postgres-metrics-sum.csv | docker exec -i clickstack-postgres-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

HyperDX でメトリクスを検証する

読み込み後、メトリクスを確認する最も簡単な方法は、あらかじめ用意されたダッシュボードを使用することです。

Dashboards and visualization セクションに進み、ダッシュボードをインポートして、多数の PostgreSQL メトリクスを一度に表示します。

タイムゾーンの表示

HyperDX はタイムスタンプをブラウザのローカルタイムゾーンで表示します。デモデータは 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC) の期間をカバーしています。場所にかかわらずデモメトリクスを確実に表示するために、タイムレンジを 2025-11-09 00:00:00 - 2025-11-12 00:00:00 に設定してください。メトリクスが表示されたら、より見やすくするために期間を 24 時間に絞り込むことができます。

ダッシュボードと可視化

ClickStack で PostgreSQL の監視を開始するにあたって、PostgreSQL メトリクス向けの基本的な可視化を提供しています。

ダッシュボード設定をダウンロード

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

HyperDX を開き、［Dashboards］セクションに移動します
右上の三点リーダーメニューから Import Dashboard をクリックします

postgres-metrics-dashboard.json ファイルをアップロードし、Finish Import をクリックします

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

ダッシュボードは、すべての可視化が事前に設定された状態で作成されます。

注記

デモデータセットの場合、時間範囲を 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC) に設定してください（ローカルタイムゾーンに合わせて調整してください）。インポートしたダッシュボードでは、デフォルトで時間範囲は指定されていません。

トラブルシューティング

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

環境変数が設定されていることを確認してください：

docker exec <コンテナ名> printenv CUSTOM_OTELCOL_CONFIG_FILE

カスタム設定ファイルがマウントされていることを確認してください：

docker exec <コンテナ名> cat /etc/otelcol-contrib/custom.config.yaml

HyperDX にメトリクスが表示されない場合

PostgreSQL にアクセスできることを確認してください。

docker exec <clickstack-container> psql -h postgres-host -U otel_monitor -d postgres -c "SELECT 1"

OTel collector のログを確認します：

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

認証エラー

パスワードが正しく設定されていることを確認してください：

docker exec <clickstack-container> printenv POSTGRES_PASSWORD

認証情報を直接検証します：

psql -h postgres-host -U otel_monitor -d postgres -c "SELECT version();"

次のステップ

PostgreSQL メトリクスの監視をセットアップしたら、次のことを実施します:

重要なしきい値（接続数上限、高いロールバック率、低いキャッシュヒット率）に対するアラートを設定する
pg_stat_statements 拡張機能でクエリレベルの監視を有効にする
異なるエンドポイントとサービス名でレシーバー設定を複製して、複数の PostgreSQL インスタンスを監視する

本番環境への移行

このガイドでは、クイックセットアップのために、ClickStack に組み込まれている OpenTelemetry Collector をベースとして利用します。本番環境では、独自の OTel Collector を稼働させ、ClickStack の OTLP エンドポイントにデータを送信することを推奨します。本番環境向けの設定については、Sending OpenTelemetry data を参照してください。

既存の PostgreSQL との統合​

前提条件​

監視ユーザーに必要な権限が付与されていることを確認する​

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

カスタム設定を用いて ClickStack をデプロイする​

メトリクス収集を検証する​

デモデータセット​

サンプルメトリクスデータセットをダウンロードする​

ClickStack を起動する​

メトリクスを ClickStack に読み込む​

HyperDX でメトリクスを検証する​

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

ダッシュボード設定をダウンロード​

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

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

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

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

HyperDX にメトリクスが表示されない場合​

認証エラー​

次のステップ​

本番環境への移行​