ClickStack - サンプルログ、トレース、メトリクス

ClickStack の入門と、ログ、セッション、トレース、メトリクスを含むサンプルデータセット

このガイドでは、サンプルデータセットを使って、ClickStack Open Source と Managed ClickStack の両方を紹介します。

Managed ClickStack

以下のガイドは、Managed ClickStack 入門ガイドを完了し、接続認証情報を控えていることを前提としています。

1. ​

   サービスを選択

   ClickHouse Cloudのメインページで、Managed ClickStack のサービスを選択します。

2. ​

   ClickStack UI (HyperDX) にアクセスする

   左側のメニューから ClickStack を選択すると、ClickStack UI が開き、自動的に認証されます。

3. ​

   サンプルデータをダウンロード

   UIにサンプルデータを表示するには、次のファイルをダウンロードしてください。

   サンプルデータ

   # curl
   curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
   # または
   # wget https://storage.googleapis.com/hyperdx/sample.tar.gz
   

   このファイルには、一般公開されている OpenTelemetry デモ のサンプルのログ、メトリクス、トレースが含まれています。これは、マイクロサービスで構成されたシンプルな e コマースストアです。このファイルを任意のディレクトリにコピーしてください。

4. ​

   サンプルデータを読み込む

   このデータを読み込むには、デプロイした OpenTelemetry (OTel) collector の HTTP エンドポイントに送信するだけです。

   次のコマンドを実行して、データを OTel collector に送信します。

   for filename in $(tar -tf sample.tar.gz); do
     endpoint="http://localhost:4318/v1/${filename%.json}"
     echo "loading ${filename%.json}"
     tar -xOf sample.tar.gz "$filename" | while read -r line; do
       printf '%s\n' "$line" | curl -s -o /dev/null -X POST "$endpoint" \
       -H "Content-Type: application/json" \
       -H "authorization: ${CLICKSTACK_API_KEY}" \
       --data-binary @-
     done
   done
   

   これは、OTLP のログ、トレース、メトリクスのソースが OTel collector にデータを送信する状況をシミュレートしたものです。本番環境では、これらのソースは各言語のクライアントや、場合によっては別の OTel collector になることもあります。

   Search ビューに戻ると、データの読み込みが始まっているはずです (データが表示されない場合は、時間範囲を Last 1 hour に調整してください) 。

   データの読み込みには数分かかります。次の手順に進む前に、読み込みが完了するまで待ってください。

5. ​

   セッションを確認する

   ユーザーから、商品の支払い時に問題が発生しているという報告があるとします。HyperDX の session replay 機能を使えば、そのときのユーザー体験を確認できます。

   左側のメニューから Client Sessions を選択します。

   このビューでは、EC ストアのフロントエンドセッションを確認できます。ユーザーがチェックアウトして購入を完了しようとするまで、セッションは Anonymous のままです。

   メールアドレスが付いている一部のセッションには関連するエラーもあり、決済失敗の報告を裏付けている可能性があります。

   失敗していてメールアドレスにも紐づいているトレースを選択します。次のビューでは、ユーザーのセッションをリプレイして問題の内容を確認できます。play を押してセッションを再生してください。

   リプレイでは、ユーザーがサイト内を移動し、商品をカートに追加していく様子を確認できます。支払いを完了しようとする場面までスキップしてかまいません。

   エラーはタイムライン上で赤く注記されます。

   ユーザーは注文を完了できませんでしたが、目立ったエラーはありません。左側のパネルの一番下までスクロールすると、ユーザーのブラウザーから送信されたネットワークイベントとコンソールイベントが表示されます。/api/checkout の呼び出し時に 500 エラーが発生していたことがわかります。

   この 500 エラーを選択します。概要 にも Column Values にも、エラーが想定外で Internal Error を引き起こしていること以外、問題の原因を示す情報はありません。

6. ​

   トレースを確認する

   完全な分散トレースを表示するには、Trace タブに移動します。

   トレースを下にスクロールすると、エラーの始点である checkout service のスパンを確認できます。Payment service のスパンを選択します。

   Column Values タブを選択して下にスクロールします。問題は cache がいっぱいになっていることに関連しているとわかります。

   上にスクロールしてトレースに戻ると、先ほどの設定により、ログがスパンに相関付けられていることがわかります。これにより、さらに詳しいコンテキストが得られます。

   payment service で cache が埋まりつつあり、そのため支払いを完了できなくなっていることが確認できました。

7. ​

   Explore でログを確認する

   さらに詳しく確認するには、Search に戻ります。

   sources から Logs を選択し、payment サービスにフィルタを適用します。

   この問題は最近発生したものですが、影響を受けた支払い件数は多いことがわかります。さらに、Visa の支払いに関連する cache が原因で問題が発生しているようです。

8. ​

   メトリクスのチャート

   コードに明らかにエラーが混入していますが、cache のサイズはメトリクスで確認できます。Chart Explorer ビューに移動します。

   データソースとして Metrics を選択します。visa_validation_cache.size (Gauge) の Maximum をプロットするようにチャートビルダーを設定し、play ボタンを押します。cache は最大サイズに達するまで明らかに増加しており、その後エラーが発生していました。

ClickStack オープンソース版

以下の例では、オールインワンイメージの手順に従ってオープンソース版 ClickStack を起動し、ローカルの ClickHouse インスタンスに接続済みであることを前提とします。

1. ​

   ClickStack UI (HyperDX) にアクセスする

   ClickStack UI にアクセスするには、http://localhost:8080 を開きます。

2. ​

   インジェスト API keyをコピー

   Team Settings を開き、API Keys セクションから Ingestion API Key をコピーします。この API key により、OpenTelemetry collector 経由のデータ インジェストが安全に行われます。

3. ​

   サンプルデータをダウンロードする

   UIにサンプルデータを表示するため、次のファイルをダウンロードします。

   サンプルデータ

   # curl
   curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
   # または
   # wget https://storage.googleapis.com/hyperdx/sample.tar.gz
   

   このファイルには、公開中の OpenTelemetry demo のサンプルのログ、メトリクス、トレースが含まれています。これは、マイクロサービスで構成されたシンプルな e コマースストアです。このファイルを任意のディレクトリにコピーしてください。

4. ​

   サンプルデータを読み込む

   このデータを読み込むには、デプロイ済みのOpenTelemetry (OTel) collectorのHTTPエンドポイントに送信するだけです。

   まず、先ほどコピーしたAPIキーをエクスポートします。

   # API キーをエクスポート
   export CLICKSTACK_API_KEY=<YOUR_INGESTION_API_KEY>
   

   データをOTel collectorに送信するには、次のコマンドを実行します。

   for filename in $(tar -tf sample.tar.gz); do
     endpoint="http://localhost:4318/v1/${filename%.json}"
     echo "loading ${filename%.json}"
     tar -xOf sample.tar.gz "$filename" | while read -r line; do
       printf '%s\n' "$line" | curl -s -o /dev/null -X POST "$endpoint" \
       -H "Content-Type: application/json" \
       -H "authorization: ${CLICKSTACK_API_KEY}" \
       --data-binary @-
     done
   done
   

   これは、OTLP のログ、トレース、メトリクスの送信元が OTel collector にデータを送信する状況をシミュレートしています。本番環境では、これらの送信元は各種言語のクライアントや、別の OTel collector である場合もあります。

   Search ビューに戻ると、データの読み込みが始まっていることを確認できます (データが表示されない場合は、時間範囲を Last 1 hour に調整してください) 。

   データの読み込みには数分かかります。次の手順に進む前に、読み込みが完了するまで待ってください。

5. ​

   セッションを調査する

   ユーザーから、商品の支払い時に問題が発生しているという報告があるとします。HyperDX のセッションリプレイ機能を使って、そのときの体験を確認できます。

   左側のメニューから Client Sessions を選択します。

   このビューでは、e コマースストアのフロントエンドセッションを確認できます。セッションは、ユーザーがチェックアウトして購入完了を試みるまで Anonymous のままです。

   メールアドレスが付いている一部のセッションには関連するエラーもあり、取引失敗の報告を裏付けている可能性があります。

   失敗しているトレースと、それに関連付けられたメールアドレスを選択します。次のビューでは、ユーザーのセッションを再生して問題を確認できます。play を押してセッションを再生してください。

   リプレイでは、ユーザーがサイト内を移動し、商品をカートに追加していく様子が表示されます。必要に応じて、支払い完了を試みる場面までスキップしてください。

   すべてのエラーは、タイムライン上に赤色で注記されます。

   ユーザーは注文を完了できませんでしたが、明らかなエラーは見当たりません。左側パネルの一番下までスクロールすると、ユーザーのブラウザーから取得したネットワークイベントとコンソールイベントが表示されます。/api/checkout の呼び出し時に 500 エラーが発生していることがわかります。

   この 500 エラーを選択します。Overview と Column Values のどちらを見ても、想定外のエラーによって Internal Error が発生していること以外に、問題の原因は示されていません。

6. ​

   トレースを確認する

   完全な分散トレースを確認するには、Trace タブに移動します。

   トレースを下にスクロールして、エラーの始点である checkout サービスのスパンを確認します。次に、Payment サービスのスパンを選択します。

   Column Values タブを選択して下にスクロールします。問題は、cache がいっぱいになっていることに関連していると分かります。

   上にスクロールしてトレースに戻ると、先ほどの設定により、ログがそのスパンに相関付けられていることが分かります。これにより、さらに詳しいコンテキストを確認できます。

   payment サービスで cache が埋まりつつあり、そのため支払いを完了できなくなっていることが分かりました。

7. ​

   ログを確認する

   さらに詳しく調べるため、Search ビュー に戻ります。

   ソースから Logs を選択し、payment サービスにフィルターを適用します。

   問題は最近発生したものですが、影響を受けた支払いの件数が多いことがわかります。さらに、Visa の支払いに関連する cache が問題を引き起こしているようです。

8. ​

   チャートメトリクス

   コードに明らかにエラーが入り込んでいますが、metrics を使って cache サイズを確認できます。Chart Explorer ビューに移動します。

   データソースとして Metrics を選択します。チャートビルダーで visa_validation_cache.size (Gauge) の Maximum を表示するよう設定し、play ボタンを押します。cache は最大サイズに達するまで明らかに増加し、その後エラーが発生しました。