> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# リモートデモデータセット
> ClickStack とリモートのデモデータセットの入門
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return ;
};
**以下のガイドは、[all-in-one image の手順](/docs/ja/clickstack/getting-started/oss)または [Local Mode Only](/docs/ja/clickstack/deployment/local-mode-only) を使用して Open Source ClickStack をデプロイし、初期ユーザーの作成を完了していることを前提としています。あるいは、ローカル環境でのセットアップをすべて省略し、このデータセットを使用している ClickStack のホストデモ [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com) に接続することもできます。**
このガイドでは、公開 ClickHouse playground の [sql.clickhouse.com](https://sql.clickhouse.com) でホストされているサンプルデータセットを使用します。このデータセットには、ローカルの ClickStack デプロイメントから接続できます。
**Managed ClickStack ではサポートされていません**
Managed ClickStack ではリモートデータベースはサポートされていません。そのため、このデータセットもサポート対象外です。
このデータセットには、公式 OpenTelemetry (OTel) デモの ClickHouse 版から取得した約 40 時間分のデータが含まれています。データは毎晩再生され、タイムスタンプは現在の時間帯に合わせて調整されるため、HyperDX に統合されたログ、トレース、メトリクスを使ってシステムの挙動を確認できます。
**データの違いについて**
このデータセットは毎日午前 0 時から再生されるため、デモを確認するタイミングによって表示される可視化は異なる場合があります。
## デモシナリオ
このデモでは、望遠鏡や関連アクセサリを販売するEC サイトで発生したインシデントを調査します。
カスタマーサポートチームから、ユーザーがチェックアウト時の支払いを完了できない問題が発生しているとの報告がありました。この問題は、調査のために Site Reliability Engineering (SRE) チームにエスカレーションされています。
SRE チームは HyperDX を使用してログ、トレース、メトリクスを分析し、問題の診断と解決を進めます。その後、セッションデータを確認し、導き出した結論が実際のユーザー行動と一致しているかどうかを確かめます。
## OpenTelemetry デモ
このデモでは、[ClickStack が保守するフォーク版](https://github.com/ClickHouse/opentelemetry-demo) の公式 OpenTelemetry デモを使用します。
### デモアーキテクチャ
このデモは、異なるプログラミング言語で実装され、gRPC と HTTP 経由で相互に通信するマイクロサービス群と、Locust を使用してユーザートラフィックを擬似的に生成するロードジェネレーターで構成されています。このデモの元のソースコードは、[ClickStack インストルメンテーション](/docs/ja/clickstack/ingesting-data/sdks/index)を使用するよう変更されています。
*出典: [https://opentelemetry.io/docs/demo/architecture/](https://opentelemetry.io/docs/demo/architecture/)*
このデモの詳細については、以下を参照してください。
* [OpenTelemetry ドキュメント](https://opentelemetry.io/docs/demo/)
* [ClickStack が管理するフォーク](https://github.com/ClickHouse/opentelemetry-demo)
## デモの手順
**このデモでは、[ClickStack SDKs](/docs/ja/clickstack/ingesting-data/sdks/index) を使ってインストルメントを行い、Kubernetes にサービスをデプロイしています。また、そこからメトリクスとログも収集しています。**
**ローカル専用モード**
Local Mode でデプロイする際に `Connect to Demo Server` をクリックした場合、この手順は省略できます。このモードを使用する場合、ログソースには `Demo_` プレフィックスが付きます (例: `Demo_Logs`) 。
`Team Settings` に移動し、`Local Connection` の `Edit` をクリックします。
接続名を `Demo` にリネームし、続いて表示されるフォームにデモサーバー用の以下の接続情報を入力します。
* `Connection Name`: `Demo`
* `Host`: `https://sql-clickhouse.clickhouse.com`
* `Username`: `otel_demo`
* `Password`: 空のままにします
**ローカル専用モード**
Local Mode でデプロイするときに `Connect to Demo Server` をクリックした場合は、この手順をスキップできます。このモードを使用する場合、ログソースには `Demo_` というプレフィックスが付きます (例: `Demo_Logs`)
上にスクロールして `Sources` に戻り、各ログソース (`Logs`、`Traces`、`Metrics`、`Sessions`) が `otel_v2` データベースを使用するように変更します。
各ログソースでデータベースの一覧全体が表示されるようにするには、ページの再読み込みが必要になる場合があります。
右上のタイムピッカーを使って時間範囲を調整し、直前の `1 day` のすべてのデータが表示されるようにします。
概要の棒グラフでは、エラー数にわずかな違いが見られ、連続するいくつかのバーで赤色が少し増えていることがあります。
バーの位置は、データセットに対してクエリを実行するタイミングによって異なります。
エラーの発生箇所を目立たせるには、`SeverityText` フィルターを使用し、`error` を選択してエラーレベルの項目だけを表示します。
これで、エラーがよりわかりやすくなるはずです。
HyperDX のクラスタリング機能を使うと、エラーを自動的に特定し、意味のあるパターンにグループ化できます。これにより、大量のログやトレースを扱う際の分析を迅速化できます。使用するには、左側のパネルにある `Analysis Mode` メニューから `イベントパターン` を選択します。
エラークラスターからは、`Failed to place order` という名前のパターンを含め、支払い失敗に関連する問題が明らかになります。さらに、カード請求の問題や cache の容量不足を示すクラスターも確認できます。
これらのエラークラスターは、異なるサービスで発生している可能性が高い点に注意してください。
ユーザーが支払いを完了できるという報告済みの問題と相関する、最もわかりやすいエラークラスター `Failed to place order` をクリックします。
これにより、`frontend` サービスに関連付けられたこのエラーの発生一覧がすべて表示されます。
表示されたエラーのいずれかを選択します。ログのメタデータが詳細に表示されます。`概要` と `Column Values` を見ていくと、cache が原因でカード請求に問題が発生していることが示唆されます。
`failed to charge card: could not charge the card: rpc error: code = Unknown desc = Visa cache full: cannot add new item.`
cache に関連するエラーが、支払い失敗の原因となっている可能性が高いことがわかりました。この問題がマイクロサービス アーキテクチャのどこで発生しているのかは、まだ特定できていません。
cache の問題を踏まえると、基盤となるインフラストラクチャを調査するのが妥当です。関連するポッドでメモリの問題が発生している可能性もあります。ClickStack では、ログとメトリクスが統合され、コンテキストに沿って表示されるため、根本原因をすばやく突き止めやすくなります。
`frontend` サービスの基盤となるポッドに関連付けられたメトリクスを表示するには、`Infrastructure` タブを選択し、時間範囲を `1d` に広げます。
この問題は、インフラストラクチャに関連しているようには見えません。エラーの前後を問わず、この期間を通して顕著に変化しているメトリクスはありません。Infrastructure タブを閉じます。
ClickStack では、トレースはログとメトリクスの両方にも自動的に相関付けられます。どのサービスが原因なのかを特定するために、選択したログにリンクされたトレースを見てみましょう。
関連するトレースを可視化するには `Trace` を選択します。続くビューを下にスクロールすると、HyperDX が各サービスのスパンをつなぎ、マイクロサービス全体にまたがる分散トレースをどのように可視化しているかがわかります。決済には明らかに複数のマイクロサービスが関与しており、その中にはチェックアウト処理や通貨換算を行うものも含まれます。
ビューの一番下までスクロールすると、`payment` サービスがエラーの原因となっており、それが呼び出しチェーンをさかのぼって伝播していることがわかります。
cache の問題により、payment サービスでユーザーが購入を完了できていないことが確認できました。根本原因についてさらに詳しく把握するため、このサービスのトレースをもう少し詳しく見ていきましょう。
`Search` を選択してメインの Search view に切り替えます。`Traces` のデータソースに切り替え、`Results table` ビューを選択します。**期間が引き続き過去1日になっていることを確認してください。**
このビューには、過去1日分のすべてのトレースが表示されます。問題は payment サービスで発生していることがわかっているため、`ServiceName` に `payment` フィルターを適用します。
`Event Patterns` を選択してトレースにイベントクラスタリングを適用すると、`payment` サービスの cache の問題をすぐに確認できます。
`Results table` をクリックして結果ビューに切り替え、`StatusCode` フィルターと `Error` 値でエラーに絞り込みます。
`Error: Visa cache full: cannot add new item.` のエラーを 1 つ選択し、`Infrastructure` タブに切り替えて期間を `1d` に広げます。
トレースとメトリクスを相関させると、`payment` サービスでメモリと CPU が増加したあと、`0` まで低下していることがわかります (これはポッドの再起動によるものと考えられます) 。このことから、cache の問題がリソース問題を引き起こした可能性が示唆されます。その結果、支払い完了時間にも影響が出ていると考えられます。
イベントデルタは、パフォーマンスやエラー率の変化を特定のデータの部分集合に関連付けることで異常を浮かび上がらせ、根本原因をすばやく特定しやすくします。
`payment` サービスに cache の問題があり、その結果リソース消費が増加していることは分かっていますが、根本原因はまだ完全には特定できていません。
結果テーブルビューに戻り、エラーが含まれる時間範囲を選択してデータを絞り込みます。エラーより前の数時間分と、可能であれば後の時間帯も選択してください (問題がまだ発生している可能性があります) 。
errors フィルターを削除し、左側の `Analysis Mode` メニューから `Event Deltas` を選択します。
上部のパネルには所要時間の分布が表示され、色はイベント密度 (スパン数) を示します。主な集中領域の外側にあるイベントの部分集合は、通常、調査する価値があります。
`1ms` を超える継続時間のイベントを選択し、`Filter by selection` フィルターを適用すると、"normal" なイベントと、継続時間が約 0ms のスパンが高密度に集まったグループとの差異を分析できます。
このデータの部分集合に対して分析を行うと、選択範囲外の "background" スパンの大半が Visa トランザクションであり、cache error による 0ms のレスポンスに関連していることが分かります。
ClickStack では、ログ、トレース、メトリクス内の任意の数値をチャート化し、より詳しいコンテキストを把握できます。
ここまでで、次のことが分かっています。
* 問題は payment service にある
* cache がいっぱいになっている
* その結果、リソース消費量が増加した
* この問題により Visa の支払いは完了できなくなった、あるいは少なくとも完了までに非常に長い時間がかかるようになった。
左側のメニューから `Chart Explorer` を選択します。支払い完了までにかかる時間をチャート化するため、以下の値を設定します。
* `Data Source`: `Traces`
* `Metric`: `Maximum`
* `SQL Column`: `Duration`
* `Where`: `ServiceName: payment`
* `Timespan`: `Last 1 day`
`▶️` をクリックすると、支払いのパフォーマンスが時間の経過とともにどのように低下したかを確認できます。
`Group By` を `SpanAttributes['app.payment.card_type']` に設定すると (オートコンプリートを使うには `card` とだけ入力します) 、Mastercard と比べて Visa トランザクションでサービスのパフォーマンスがどのように低下したかを確認できます。
なお、エラーが発生すると、レスポンスは `0s` で返るようになります。
最後に、cache サイズをメトリクスとしてプロットし、時間の経過に伴ってどのように推移したかを確認して、より多くのコンテキストを得ましょう。
次の値を入力します:
* `Data Source`: `Metrics`
* `Metric`: `Maximum`
* `SQL Column`: `visa_validation_cache.size (gauge)` (`cache` と入力するだけでオートコンプリートされます)
* `Where`: `ServiceName: payment`
* `Group By`: ``
cache サイズは、4〜5時間かけて増加し (おそらくソフトウェアのデプロイメント後) 、最終的に最大サイズ `100,000` に達したことがわかります。`Sample Matched Events` からは、cache がこの上限に達したタイミングとエラーが相関していること、またその後はサイズが `0` と記録され、レスポンスも `0s` で返されるようになっていることがわかります。
要約すると、logs、traces、そして最後にメトリクスを調査することで、次のことがわかりました:
* 問題は payment service にあります
* おそらくデプロイメントに伴うサービス動作の変更により、4〜5時間にわたって visa cache が徐々に増加し、最大サイズ `100,000` に達しました
* その結果、cache のサイズ増大に伴って consumption も増加しました。おそらく実装上の問題が原因です
* cache が増大するにつれて、Visa 決済のパフォーマンスは低下しました
* 最大サイズに達すると、cache は決済を拒否し、自身のサイズを `0` と報告しました。
セッションを使うとユーザー体験を再生でき、ユーザーの視点から `error` がどのように発生したかを視覚的に確認できます。通常、根本原因の特定に使われることはあまりありませんが、カスタマーサポートに報告された問題の確認には有用で、より詳しい調査の出発点にもなります。
HyperDX では、セッションはトレースやログに関連付けられており、根本原因まで含めて全体像を把握できます。
たとえば、サポートチームから支払いに問題が発生したユーザーのメールアドレス `Ronny.Windler@gmail.com` が共有された場合、ログやトレースを直接検索するよりも、まずそのユーザーのセッションから確認するほうが効果的なことがよくあります。
左側のメニューから `Client Sessions` タブを開き、データソースが `Sessions`、時間範囲が `Last 1 day` に設定されていることを確認します。
`SpanAttributes.userEmail: Ronny.Windler` を検索して、対象の顧客のセッションを見つけます。セッションを選択すると、左側にその顧客のセッションに対応するブラウザーイベントと関連するスパンが表示され、右側にはユーザーのブラウザー操作が再現されます。
▶️ ボタンを押すと、セッションを再生できます。`Highlighted` と `All Events` を切り替えることで、span の粒度を変更でき、前者では主要なイベントとエラーが強調表示されます。
span の一番下までスクロールすると、`/api/checkout` に関連する `500` エラーを確認できます。この特定の span の ▶️ ボタンを選択すると、再生位置がセッション内のこの時点に移動するため、顧客の体験を確認できます。支払いは単に機能していないように見え、エラーも表示されていません。
span を選択すると、これが内部エラーによって発生したことを確認できます。`Trace` タブをクリックし、接続されている span をスクロールしていくことで、この顧客が実際に当社の cache の問題の影響を受けていたことを確認できます。