ClickStack のイベントデルタ
イベントデルタは、レイテンシヒートマップと自動属性分析を組み合わせることで、クエリを書かなくてもトレースデータの傾向を把握し、遅いスパンがなぜ異なるのかを特定できる機能です。使用方法は 3 つあります。
- 分布モード (常時有効) — ヒートマップで選択範囲がない場合は、現在のスパン群に対する各属性の値の分布が表示されます。支配的な値や異常にまれな値 (カーディナリティの外れ値) を見つけるのに役立ちます。
- 比較モード — ヒートマップ上で長方形をドラッグすると、その内側のスパン (Selection) と外側のすべて (Background) を比較できます。差異の切り分けに役立ちます。
- 反復的なドリルダウン — 任意のバーをクリックすると、その値で絞り込み (または除外) できます。ヒートマップは絞り込み後のスパン群に対して再描画されるため、原因が明らかになるまでさらに絞り込めます。
前提条件
イベントデルタを使用するには、duration 式を持つTraceデータソースが必要です。スパンデータを生成する OpenTelemetry 計装済みのサービスであれば、どれでも使用できます。すべての ClickStack デプロイ形態 (Managed、Open Source、ClickHouse Cloud) で利用できます。
はじめに
- Data Source ドロップダウンから、トレースを含むソースを選択します。ソース名は任意ですが、重要なのは、そのソースが Trace タイプとして設定されていることです。イベントデルタ タブは、そのようなソースでのみ有効になります。
- Analysis Mode セクションで、イベントデルタ タブをクリックします。
イベントデルタは、Results Table や Event Patterns と並ぶ独立した分析モードです。これに切り替えると、表示はヒートマップと属性分析グリッドに切り替わりますが、検索フィルターとタイムレンジは保持され、いつでも元に戻せます。
ヒートマップ
ヒートマップでは、スパンを 2 つの軸でプロットします。
- X 軸 — 時間
- Y 軸 — 数値 (既定では スパンの継続時間 (ミリ秒、対数スケール) )
色の濃淡は、ビンごとのイベント数を示します。明るいほど スパンが多くなります。
ヒートマップを見るだけで、二峰性のレイテンシ、特定の時刻に発生するレイテンシスパイク、あるいは一貫して低速な スパンの帯といったパターンを読み取れます。ある領域を調査するには、その上で長方形を描くようにクリック＆ドラッグします。これが Selection となり、下の分析が比較モードに切り替わります。
分布モード: カーディナリティの外れ値
ヒートマップで何も選択していない場合、分析パネルには属性ごとに1つの棒グラフが表示され、条件に一致するすべてのスパンを対象に集計されます。凡例には All spans と表示されます。
属性は、値の集中度合いに応じて順位付けされます。少数の値に偏っている属性ほど先に表示され、値が一様に分散しエントロピーの高い属性は後順位になります。
分布モードは、データの カーディナリティの傾向 を把握したい場合に使用します。
- 高頻度 — どのサービス、エンドポイント、ステータスコード、またはホストがスパン全体の大部分を占めているかを確認します。多くの場合、トラフィックの大半を占める単一のテナント、バージョン、またはルートが見えてきます。
- 低頻度 — 出現はするものの、まれにしか現れない値です。スパンの
0.5%にしか現れないステータスコードや、ほとんど出てこないホストが、最も重要なシグナルであることもあります。回帰や異常な振る舞いは、こうしたロングテールに潜んでいることが多いためです。
まず検索バーと組み合わせて対象を絞り込み (例: エラースパンのみ、クライアントスパンのみ、1つのエンドポイントのみ) 、そのうえでその子集の分布を確認してください。
比較モード：通常時との差分
ヒートマップ上で長方形をドラッグして選択し、Filter by Selection をクリックすると、比較モードに入ります。選択したスパンは Selection (赤いバー) となり、それ以外は Background (緑のバー) になります。各属性チャートにはこの 2 つの集団が並べて表示され、差が最も大きい属性ほど先頭に来るように並べ替えられます。つまり、片方にほぼのみ存在する値 (または片方には存在しない値) が、違いを生み出している有力な候補です。
どの長方形でも機能しますが、選択方法には 3 つのパターンがあり、それぞれ異なる問いに答えます。
- 違和感のある領域 — 特定の時間帯に限って現れる高レイテンシの帯、目に見える回帰の始まり、ほかと傾向が合わないスパンの集まり。ヒートマップ上ですでに怪しい箇所が見えているときに使います。
- 全幅の垂直分割 (低速 vs 高速) — タイムレンジ全体にわたって、上側の高レイテンシ帯域 (遅い側の裾) だけを覆う長方形をドラッグし、高速なスパンの大半を Background として残します。低速なスパンが高速なスパンと比べて何が違うのかを比較できます。
- 全高の水平分割 (変更前 vs 変更後) — レイテンシ軸全体にわたって、変更が疑われる後の時間帯だけを覆う長方形をドラッグし、それ以前の期間を Background として残します。レイテンシとは切り離して、2 つの時間帯の間で何が変わったのかを比較できます。
全範囲にわたる垂直分割と水平分割は、ヒートマップ上で視覚的に目立つものがない場合に特に有効です。目で異常を探すのではなく、属性分析に差分の特定を任せられます。
反復的なドリルダウン
比較モードと分布モードは、組み合わせて使うと最も効果を発揮します。いずれかのバーをクリックすると、3 つのアクションを含むポップオーバーが開きます。
- Filter — この値を持つスパンだけを残します
- Exclude — この値を持つスパンを除外します
- Copy — 値をクリップボードにコピーします
Filter または Exclude を適用すると、ヒートマップの選択はクリアされ、ヒートマップは新しい母集団に対して再描画され、分布モードはそのフィルタ済みの集合を対象に再開されます。ヒートマップの形がどう変わるかを確認してください。フィルタが成功すると、遅い帯域が目に見えて消えたり、二峰性の分離が縮小したりします。これを繰り返します。次に疑わしい値を見つけてフィルタし、新しいヒートマップを見て、新しい分布を確認します。通常は数回繰り返すだけで、回帰の原因を 1 つか 2 つの属性に絞り込めます。
低頻度の値をまとめた集約済みの Other (N) バケットはクリックできません。そのバケット内の特定の値でフィルタするには、検索バー を直接使用してください。
母集団が十分に小さくなったら、Results Table タブに切り替えて個々のトレースを確認します。フィルタはそのまま引き継がれます。
ヒートマップをカスタマイズする
ヒートマップ右上の歯車アイコンをクリックすると、Heatmap Settings ドロワーが開きます。
| パラメーター | デフォルト | 説明 |
|---|---|---|
| Scale | Log | Log は遅延の広い範囲を扱うのに適しています。Linear は、範囲が狭く均一な分布に適しています。 |
| Value | (Duration)/1e6 | 任意の数値式です。たとえば、レスポンスサイズ、エラー率、カスタムの スパン属性などを指定できます。 |
| Count | count() | 色分けに使用する集計です。avg()、sum()、p95()、または countDistinct(field) のような式に切り替えられます。 |
Apply をクリックするとヒートマップが更新され、下部の属性分析にも反映されます。
トラブルシューティング
イベントデルタ タブが表示されない
Analysis Mode の イベントデルタ タブは、duration 式を持つ Trace ソースを選択した場合にのみ表示されます。データソースが Trace タイプとして設定されており、duration 情報を含むスパンデータがあることを確認してください。
属性チャートにほとんど、またはまったく結果が表示されない
サンプル数が少なすぎる場合 (スパンが数十件未満) 、分布に統計的な意味がないことがあります。タイムレンジを広げるか、検索フィルターを緩めてください。
