05 ClickStack

ローカルのステートレスなコレクターでテレメトリを転送し、Managed ClickStack を有効化して、クラウドホストの HyperDX で確認します。

開始時点

build-workshop-v1 にいます — チェックアウトは不要です。所要時間は約 15分 です。アプリはすでに OpenTelemetry 用に計装されています。このモジュールでは、コレクターのオーバーレイでそれを有効にします。

前提条件: 自分の Cloud サービスが動いていること（モジュール 01）。

なぜ

後でアプリを診断するには、まずアプリの中を見られる必要があります。ClickStack（ClickHouse のオブザーバビリティスタックで、UI が HyperDX）は、OpenTelemetry のトレースとログを ClickHouse に保存します。このモジュールでコレクターを有効にすると、アプリを通るすべてのリクエストが、クエリ可能なテレメトリを生み出すようになります。

ゴール

アプリのトレースとバックエンドのクエリログが ClickStack に流れ込み、少なくとも1つのエンドツーエンドのリクエストトレースと、成功したクエリの記録が継続的に見えている状態。

ステップ 1 — OpenTelemetry コレクターのオーバーレイを実行する

HyperDX、ストレージ、クエリの計算リソースは ClickHouse Cloud のマネージドのままです。ここでローカルにあるのは、ローカルアプリの隣で動くステートレスな OpenTelemetry コレクターだけです。これはテレメトリを転送するもので、ローカルの ClickStack や HyperDX のデプロイではありません。

まずコレクターのポートを確認してください

コレクターはホストのポート 4317 と 4318 で OTLP を公開しますが、これらはすでに使われていることがよくあります。モジュール 00 で ClickHouse_Demos/workshops/build_workshop/app の ./preflight.sh がこれらについて WARN を出した場合は、オーバーレイを起動する前に .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 を再実行して、ポートが空いていることを確認できます。

`.env.workshop` と `docker-compose.otel.yml`

これらは .env.workshop.example の ClickStack オブザーバビリティセクションにあります。自分の .env.workshop で値を埋めてください。

OTLP_AUTH_TOKEN=change-me-workshop-token   # shared secret securing OTLP ingest
CLICKSTACK_DATABASE=otel                   # ClickStack's own otel_* tables
OTEL_SERVICE_NAME=nyc-taxi-backend         # the service name shown in HyperDX
LOG_LEVEL=DEBUG                            # show successful queries in Log source

このファイルをシェルに source しないでください。下の Compose コマンドはこのファイルを直接読み込みます。そうすることでパスワードや API キーが export されたシェル変数に入らず、後からファイルを編集した内容も反映されます。

では、オーバーレイ付きでスタックを起動します。オーバーレイはバックエンドに OTEL_ENABLED=true を設定し、otel-collector サービス（clickhouse/clickstack-otel-collector）を追加し、ブラウザのテレメトリ設定でフロントエンドを再ビルドします。

docker compose --env-file .env.workshop \
  -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build

コレクターは .env.workshop の CLICKHOUSE_HOST / CLICKHOUSE_PORT / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD を再利用します。バックエンドは OTLP を http://otel-collector:4318（HTTP/protobuf）にエクスポートします。Linux ホストでコンテナの生の stdout も収集したい場合は、--profile container-logs を追加してください。

ステップ 2 — 自分のサービスで Managed ClickStack を有効化する

このワークショップでは、自分の ClickHouse Cloud サービス内の Managed ClickStack (HyperDX) を使います。コレクターが自分のサービスに otel_* テーブルを書き込み、HyperDX の UI がそこでそれらを描画します。コンソールで有効化します。

コンソール - 自分のサービス -> ClickStack -> Start Ingestion -> コレクターの手順はスキップ（アプリのコレクターはステップ 1 ですでに動いています）-> Launch ClickStack

これでシングルサインオンで HyperDX に入れます。テレメトリはすでに流れ始めているので、ホストされた UI は開いた直後からデータで埋まり始めます。

Managed ClickStack: 従来のセットアップとの相違点

バックエンドは、ClickStack のドキュメントが推奨する便利パッケージ hyperdx-opentelemetry ではなく、素の OpenTelemetry を使っています。あのパッケージは opentelemetry-api==1.30.0 を厳密に固定しており、チャット機能が使う Langfuse v4 SDK （opentelemetry-api>=1.33.1 が必要）と競合します — この2つは1つの環境を共有できません。 ClickStack のコレクターは標準の OTLP を取り込むので、素のディストリビューションでもまったく同じように動作します。ワークショップでは単に、エクスポーターの環境変数を自分で設定しています。
ClickStack のテレメトリは、自分のサービス上の別のデータベース（CLICKSTACK_DATABASE=otel）に置かれ、アプリのデータのデータベース（CLICKHOUSE_DATABASE=nyc_tlc_data）とは区別されます。
トレースとバックエンドの Python ログは、自動計装されたバックエンドから OTLP で流れます。オプションの --profile container-logs のコレクターは、乗車データのライターのような計装されていないサービス向けのものです。その Linux Docker のログパスは Docker Desktop では利用できない場合があります。

ステップ 3 — トラフィックを発生させて ClickStack で見つける

Ops ダッシュボードを開き、デフォルトの 1m の間隔と 5s の自動更新のまま約30秒放置します。その後 ClickStack を開きます。

Traces で、1つのリクエストをエンドツーエンドで追います（フロントエンド -> バックエンド -> ClickHouse）。
Logs で nyc-taxi-backend を選び、繰り返される ClickHouse query ok の記録を探します。タイムスタンプは更新ごとに進むはずです。
severity を意味のある状態に保ってください。成功したクエリは DEBUG です。実際のアイドル復帰リトライや失敗は WARNING または ERROR として現れます。

HyperDX に nyc-taxi-backend という名前のサービスが現れ、/api/... へのリクエストがトレースとして表示され、それぞれが子スパンの clickhouse.query を持っているのが見えるはずです。

nyc-taxi-backend のトレースを表示している HyperDX の Search ビュー — timestamp、service、duration の列を持つ GET /api/health と POST のスパンのライブ一覧

アプリのトレースを描画する HyperDX: nyc-taxi-backend サービスとその /api/... リクエストのスパン。

完了したかどうかの確認方法

HyperDX に nyc-taxi-backend という名前のサービスが現れる。
/api/... へのリクエストがトレースとして表示され、それぞれが db.statement、 db.elapsed_ms、db.rows_returned を持つ子スパン clickhouse.query を伴っている。
Ops ダッシュボードを開いたままにしている間、Log source に新しい DEBUG ... ClickHouse query ok の記録が表示される。
ここではまだクエリのエラーは見えません。健全でデータの入ったアプリは安全上の上限に触れず、 4xx のリクエストは ClickHouse まで届きません。モジュール 07 では、注入された障害によってエラーになった clickhouse.query スパン（error.category 付き）が観測できるようになります。

まとめ

これでアプリは観測可能になりました。トレースとバックエンドのクエリログが ClickHouse に記録され、 ClickStack で探索できます。オプションの container-logs プロファイルは、対応する Linux ホストで乗車データのライターの stdout も追加します。このテレメトリが、次の AI SRE の作業の土台になります。

終了状態

テレメトリが ClickStack に流れ込んでいます。06 AI SRE に進んで、その上にエージェントで構築しましょう。