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

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

Managed ClickStack
ClickStack Open Source

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

サービスを選択

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

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

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

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

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

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

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

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

このデータを読み込むには、デプロイした 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 に調整してください) 。データの読み込みには数分かかります。次の手順に進む前に、読み込みが完了するまで待ってください。

セッションを確認する

ユーザーから、商品の支払い時に問題が発生しているという報告があるとします。HyperDX の session replay 機能を使えば、そのときのユーザー体験を確認できます。左側のメニューから Client Sessions を選択します。このビューでは、EC ストアのフロントエンドセッションを確認できます。ユーザーがチェックアウトして購入を完了しようとするまで、セッションは Anonymous のままです。メールアドレスが付いている一部のセッションには関連するエラーもあり、決済失敗の報告を裏付けている可能性があります。失敗していてメールアドレスにも紐づいているトレースを選択します。次のビューでは、ユーザーのセッションをリプレイして問題の内容を確認できます。play を押してセッションを再生してください。リプレイでは、ユーザーがサイト内を移動し、商品をカートに追加していく様子を確認できます。支払いを完了しようとする場面までスキップしてかまいません。

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

ユーザーは注文を完了できませんでしたが、目立ったエラーはありません。左側のパネルの一番下までスクロールすると、ユーザーのブラウザーから送信されたネットワークイベントとコンソールイベントが表示されます。/api/checkout の呼び出し時に 500 エラーが発生していたことがわかります。この 500 エラーを選択します。概要 にも Column Values にも、エラーが想定外で Internal Error を引き起こしていること以外、問題の原因を示す情報はありません。

トレースを確認する

完全な分散トレースを確認するには、Trace タブに移動します。トレースを下にスクロールして、エラーの始点である checkout サービスのスパンを確認します。次に、Payment サービスのスパンを選択します。Column Values タブを選択して下にスクロールします。問題は、cache がいっぱいになっていることに関連していると分かります。上にスクロールしてトレースに戻ると、先ほどの設定により、ログがそのスパンに相関付けられていることが分かります。これにより、さらに詳しいコンテキストを確認できます。payment サービスで cache が埋まりつつあり、そのため支払いを完了できなくなっていることが分かりました。

Explore でログを確認する

さらに詳しく確認するには、Search に戻ります。sources から Logs を選択し、payment サービスにフィルタを適用します。この問題は最近発生したものですが、影響を受けた支払い件数は多いことがわかります。さらに、Visa の支払いに関連する cache が原因で問題が発生しているようです。

チャートメトリクス

コードに明らかにエラーが入り込んでいますが、metrics を使って cache サイズを確認できます。Chart Explorer ビューに移動します。データソースとして Metrics を選択します。チャートビルダーで visa_validation_cache.size (Gauge) の Maximum を表示するよう設定し、play ボタンを押します。cache は最大サイズに達するまで明らかに増加し、その後エラーが発生しました。

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

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

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

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

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

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

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

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

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

このデータを読み込むには、デプロイ済みのOpenTelemetry (OTel) collectorのHTTPエンドポイントに送信するだけです。まず、先ほどコピーしたAPIキーをエクスポートします。

# export API key
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

セッションを確認する

ユーザーから、商品の支払い時に問題が発生しているという報告があるとします。HyperDX のセッションリプレイ機能を使って、そのときの体験を確認できます。左側のメニューから Client Sessions を選択します。このビューでは、e コマースストアのフロントエンドセッションを確認できます。セッションは、ユーザーがチェックアウトして購入完了を試みるまで Anonymous のままです。メールアドレスが付いている一部のセッションには関連するエラーもあり、取引失敗の報告を裏付けている可能性があります。失敗しているトレースと、それに関連付けられたメールアドレスを選択します。次のビューでは、ユーザーのセッションを再生して問題を確認できます。play を押してセッションを再生してください。リプレイでは、ユーザーがサイト内を移動し、商品をカートに追加していく様子が表示されます。必要に応じて、支払い完了を試みる場面までスキップしてください。

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

ユーザーは注文を完了できませんでしたが、明らかなエラーは見当たりません。左側パネルの一番下までスクロールすると、ユーザーのブラウザーから取得したネットワークイベントとコンソールイベントが表示されます。/api/checkout の呼び出し時に 500 エラーが発生していることがわかります。この 500 エラーを選択します。Overview と Column Values のどちらを見ても、想定外のエラーによって Internal Error が発生していること以外に、問題の原因は示されていません。

トレースを確認する

ログを確認する

さらに詳しく調べるため、Search ビューに戻ります。ソースから Logs を選択し、payment サービスにフィルターを適用します。問題は最近発生したものですが、影響を受けた支払いの件数が多いことがわかります。さらに、Visa の支払いに関連する cache が問題を引き起こしているようです。

チャートメトリクス