05 ClickStack

学習者向けレッスン 05 ClickStack に対応するファシリテーター用の手引きです。

タイミング

約15分。モジュール 07 のインシデントラボの前にテレメトリーが蓄積されている必要があるため、 このモジュールで可能な限り早くコレクターを起動し、動かし続けてください。

トークトラック

• マネージド ClickStack はテレメトリーを ClickHouse Cloud に格納し、HyperDX がホスト型の UI になる。 ローカルのコレクターはデータを転送するだけ。エンドツーエンドのリクエストトレースと、Log ソースにある 新しい DEBUG ... ClickHouse query ok のレコードの両方を見せる。
• ステップ 2 でマネージド ClickStack を起動する前に、ステップ 1 でコレクターを起動させること。 これでテレメトリーが到着する時間ができ、ホスト UI の最初のビューが役に立つものになる。
• プロジェクターでエンドツーエンドのリクエストトレースを1つ見せる。

よくある失敗

• OTLP のホストポート 4317/4318 が既に使用中: .env.workshop に OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT を設定させ（preflight が値を提案する。例: 24317/24318）、 クローンしたリポジトリ内のどこからでも cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh を実行させる。 バックエンドはネットワーク内でコレクターに到達するため、このポート変更は安全である。
• コレクターのオーバーレイを起動していない（2つ目の -f docker-compose.otel.yml を忘れた）ため、 HyperDX に何も届かない。
• OTLP_AUTH_TOKEN の不一致、または .env.workshop の CLICKHOUSE_* の欠落（コレクターは Cloud サービスへ到達するために CLICKHOUSE_HOST/PORT/USER/PASSWORD を再利用する）。
• まだトラフィックが発生していない。両方のダッシュボードをクリックして回らせる。
• Docker Desktop では、オプションの --profile container-logs スクレイパーがホストのログパスを マウントできない（デーモンが VM 内にあるため）。これは想定どおり。バックエンドのログは OTLP 経由で送られる。 HyperDX が空のときにフォワーダーを診断する目的でのみ docker compose ... logs を使う。
• オーバーレイがバックエンドを再作成した後、以前はアプリが 502 を返していた（フロントエンドの nginx が 古いバックエンドの IP をキャッシュしていた）。現在はフロントエンドがリクエストごとに名前解決をやり直すため、 約10秒で自己修復し、手動の再起動は不要。ドライランで修正を確認済み。
• ドライランの参考値: テレメトリーのパイプラインをエンドツーエンドで検証済み — nyc-taxi-backend の トレースに、db.statement / db.elapsed_ms / db.rows_returned を持つ clickhouse.query の 子スパンが含まれていた。2026-07 のクリーンルームでのドライランで確認済み。

リセット手順

• 両方の compose ファイルを指定して再起動する: docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build。
• Cloud コンソールでサービスを開き、ClickStack を選択し、SSO セッションが期限切れならホスト UI を 起動し直す。