ClickStackでTemporal Cloudのメトリクスを監視

警告Temporal プラットフォームでの OpenMetrics のサポートは、Public Preview として提供されています。詳細については、Temporal のドキュメントを参照してください。

Temporal は、シンプルでありながら高度で耐障害性の高いアプリケーションを構築するための抽象化を提供します。

要点OTel Prometheus receiver を使用して、ClickStack で Temporal Cloud のメトリクスを監視します。あらかじめ用意されたダッシュボードも含まれています。

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

このセクションでは、Prometheus receiver を使用するように ClickStack OTel collector を設定して、ClickStack を構成する方法を説明します。

前提条件

稼働中の ClickStack インスタンス
既存の Temporal Cloud アカウント
ClickStack から Temporal Cloud への HTTP ネットワークアクセス

Temporal Cloud キーを作成する

Temporal Cloud の API キーを用意してください。これは、Temporal のドキュメントにある認証ガイドに従って作成できます。

キーファイルこれらの認証情報は、以下で作成する設定ファイルと同じディレクトリにある temporal.key ファイルに保存してください。このキーは、前後に空白を入れず、プレーンテキストとしてそのまま保存する必要があります。

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

ClickStack では、カスタム設定ファイルをマウントして環境変数を設定することで、ベースの OpenTelemetry collector 設定を拡張できます。このカスタム設定は、OpAMP 経由で HyperDX が管理するベース設定にマージされます。temporal-metrics.yaml という名前のファイルを、次の設定内容で作成します。

temporal-metrics.yaml

receivers:
  prometheus/temporal:
    config:
      scrape_configs:
      - job_name: 'temporal-cloud'
        scrape_interval: 60s
        scrape_timeout: 30s
        honor_timestamps: true
        scheme: https
        authorization:
          type: Bearer
          credentials_file: /etc/otelcol-contrib/temporal.key
        static_configs:
          - targets: ['metrics.temporal.io']
        metrics_path: '/v1/metrics'

processors:
  resource:
    attributes:
      - key: service.name
        value: "temporal"
        action: upsert

service:
  pipelines:
    metrics/temporal:
      receivers: [prometheus/temporal]
      processors:
        - resource
        - memory_limiter
        - batch
      exporters:
        - clickhouse

この構成では、次のことを行います。

metrics.temporal.io の Temporal Cloud に接続します
60秒ごとにメトリクスを収集します
主要なパフォーマンスメトリクスを収集します
OpenTelemetry セマンティック規約に従って、必須の service.name リソース属性を設定します
専用のパイプラインを介してメトリクスを ClickHouse エクスポーターにルーティングします

カスタム設定で定義するのは、新しい receiver、プロセッサ、パイプラインのみです
memory_limiter と batch のプロセッサ、および clickhouse エクスポーターは、ベースの ClickStack 構成で既に定義されているため、ここでは名前で参照するだけです
resource プロセッサは、OpenTelemetry セマンティック規約に従って必須の service.name 属性を設定します
Temporal Cloud アカウントが複数ある場合は、それらを区別できるように service.name をカスタマイズしてください (例: "temporal-prod"、"temporal-dev")

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

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

カスタム設定ファイルを /etc/otelcol-contrib/custom.config.yaml にマウントする
環境変数 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml を設定する
temporal.key ファイルを /etc/otelcol-contrib/temporal.key にマウントする
ClickStack と Temporal 間のネットワーク接続を確保する

以降のすべてのコマンドは、temporal-metrics.yaml と temporal.key が保存されているサンプルディレクトリで実行することを前提としています。

オプション 1: Docker Compose

ClickStack デプロイメントの設定を更新します。

services:
  clickstack:
    # ... 既存の設定 ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
    volumes:
      - ./temporal-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - ./temporal.key:/etc/otelcol-contrib/temporal.key: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)/temporal-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/temporal.key:/etc/otelcol-contrib/temporal.key:ro" \
  clickhouse/clickstack-all-in-one:latest

HyperDX でメトリクスを確認する

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

Metrics エクスプローラーに移動します
temporal で始まるメトリクスを検索します (例: temporal_cloud_v1_workflow_success_count、temporal_cloud_v1_poll_timeout_count)
設定した収集間隔でメトリクスのデータポイントが表示されるはずです

ダッシュボードと可視化

ClickStack で Temporal Cloud の監視をすぐに始められるよう、Temporal メトリクス向けの可視化例をいくつか用意しています。

ダッシュボード設定

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

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

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

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

すべての可視化があらかじめ設定された状態でダッシュボードが作成されます。

トラブルシューティング

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

環境変数 CUSTOM_OTELCOL_CONFIG_FILE が正しく設定されているか確認してください。

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

カスタム構成ファイルが /etc/otelcol-contrib/custom.config.yaml にマウントされていることを確認してください。

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
# 通常は、docker exec clickstack ls -lh /etc/otelcol-contrib/custom.config.yaml

カスタム設定の内容を表示し、正しく読み取れることを確認します:

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
# 通常は、docker exec clickstack cat /etc/otelcol-contrib/custom.config.yaml

temporal.key がコンテナにマウントされていることを確認します。

docker exec <container-name> cat /etc/otelcol-contrib/temporal.key
# 通常は、docker exec clickstack cat /etc/otelcol-contrib/temporal.key
# temporal.key の内容が出力されれば成功です

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

collector から Temporal Cloud にアクセス可能であることを確認します。

# ClickStackコンテナーから実行
docker exec <container-name> curl -H "Authorization: Bearer <API_KEY>" https://metrics.temporal.io/v1/metrics

たとえば、Prometheus のメトリクスが一連表示されるはずです。

temporal_cloud_v1_workflow_success_count{operation="CompletionStats",region="aws-us-east-2",temporal_account="l2c4n",temporal_namespace="clickpipes-aws-prd-apps-us-east-2.l2c4n",temporal_task_queue="clickpipes-svc-dc118d12-b397-4975-a33e-c2888ac12ac4-peer-flow-task-queue",temporal_workflow_type="QRepPartitionWorkflow"} 0.067 1765894320

現在有効な設定に Prometheus receiver が含まれていることを確認してください:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "Prometheus:"
## 通常は: docker exec clickstack cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "prometheus:"

collector agent のログにエラーがないか確認します：

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus
# 接続エラーまたは認証失敗を確認する
# docker exec clickstack cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus

collectorのログを確認してください:

docker exec <container> cat /var/log/otel-collector.log | grep -i error
# 設定のパースエラーを確認する - 起動直後の supervisor.opamp-client のエラーは無視して構わない 
# docker exec clickstack cat /var/log/otel-collector.log | grep -i error

認証エラー

ログに認証エラーが表示されている場合は、API keyを確認してください。

ネットワーク接続の問題

ClickStack から Temporal Cloud に接続できない場合は、Docker Compose ファイルまたは docker run コマンドで外部ネットワーク接続が許可されていることを確認してください。

次のステップ

重要なメトリクス (ワークフローの失敗率、タスクのバックログ増加、スケジュールから開始までのレイテンシ) に対するalertsを設定します
特定のユースケース (ネームスペースレベルの監視、ワークフロータイプごとのパフォーマンス) 向けに、追加のダッシュボードを作成します
receiver 設定を異なるエンドポイントとサービス名で複製し、複数の Temporal Cloud アカウントを監視します

本番環境での運用

このガイドでは、すばやくセットアップできるように、ClickStack に組み込まれている OpenTelemetry Collector を利用しています。本番環境でデプロイする場合は、独自の OTel Collector を実行し、データを ClickStack の OTLP エンドポイントに送信することを推奨します。本番環境向けの設定については、OpenTelemetry データの送信を参照してください。

​既存の Temporal Cloud とのインテグレーション

​前提条件

​Temporal Cloud キーを作成する

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

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

オプション 1: Docker Compose

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

​HyperDX でメトリクスを確認する

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

​ ダッシュボード設定

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

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

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

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

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

​認証エラー

​ネットワーク接続の問題

​次のステップ

​本番環境での運用

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

前提条件

Temporal Cloud キーを作成する

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

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

HyperDX でメトリクスを確認する

ダッシュボードと可視化

ダッシュボード設定

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

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

トラブルシューティング

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

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

認証エラー

ネットワーク接続の問題

次のステップ

本番環境での運用