Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

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

前提条件

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

Temporal Cloud キーを作成する

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

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

ClickStack では、カスタム設定ファイルをマウントして環境変数を設定することで、ベースの OpenTelemetry collector 設定を拡張できます。このカスタム設定は、OpAMP 経由で HyperDX が管理するベース設定にマージされます。

temporal-metrics.yaml という名前のファイルを、次の設定内容で作成します。

temporal-metrics.yamlyaml
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

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

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

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

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

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

オプション 1: Docker Compose

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

services:
  clickstack:
    # ... existing configuration ...
    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
      # ... other volumes ...
オプション 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 にログインし、メトリクスが取り込まれていることを確認します。

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

ダッシュボードと可視化

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

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

ダッシュボード設定ファイルをダウンロード。

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

  1. HyperDX を開き、Dashboards セクションに移動します
  2. 右上の三点メニューから Import Dashboard をクリックします
ダッシュボードのインポートボタン
  1. temporal-metrics-dashboard.json ファイルをアップロードし、Finish Import をクリックします
インポート完了ダイアログ

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

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

Temporal メトリクスのダッシュボード

トラブルシューティング

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

環境変数 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 データの送信を参照してください。

Navigation