ClickStack のイベントデルタ
イベントデルタは、レイテンシヒートマップと自動属性分析を組み合わせることで、クエリを書かなくてもトレースデータの傾向を把握し、遅いスパンがなぜ異なるのかを特定できる機能です。使用方法は 3 つあります。
- 分布モード (常時有効): ヒートマップで選択範囲がない場合は、現在のスパン群に対する各属性の値の分布が表示されます。支配的な値や異常にまれな値 (カーディナリティの外れ値) を見つけるのに役立ちます。
- 比較モード: ヒートマップ上で長方形をドラッグすると、その内側のスパン (Selection) と外側のすべて (Background) を比較できます。差異の切り分けに役立ちます。
- 反復的なドリルダウン: 任意のバーをクリックすると、その値で絞り込み (または除外) できます。ヒートマップは絞り込み後のスパン群に対して再描画されるため、原因が明らかになるまでさらに絞り込めます。
上のスクリーンショットでは、ヒートマップの右端はおよそ 10 ms を示しており、午前中を通して維持されていた 1 ms のベースラインには戻っていません。劣化はまだ進行中であり、インシデントの最中の状態を捉えています。
前提条件
イベントデルタを使用するには、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つのエンドポイントのみ) 、そのうえでその子集の分布を確認してください。
比較モード：通常時との差分
ヒートマップ上で長方形をクリックしてドラッグすると、比較モードに入ります。選択したスパンは Selection (オレンジ色のバー) となり、それ以外は Background (緑のバー) になります。各属性チャートにはこの 2 つの集団が並べて表示され、差が最も大きい属性ほど先頭に来るように並べ替えられます。つまり、片方にほぼのみ存在する値、または片方には存在しない値が、違いを生み出している有力な候補です。
描く長方形の形によって、何を見極めたいのかが変わります。代表的な 2 つの形を以下で説明します。
ユースケース 1: 回帰の前後
ヒートマップで、タイムラインに沿ってレイテンシが上昇していく様子が見える場合 (遅い帯が厚くなる、明るい帯が上に移動する、あるいは健全な期間と劣化した期間の境目に明確な変曲点がある場合) は、その立ち上がりの変曲点からウィンドウの右端まで長方形をドラッグします。比較をより明瞭にするには、長方形の下端を軸の最下端ではなく健全時のベースラインに合わせてください。こうすることで、同じ時間範囲にたまたま含まれた、まだ健全な高速スパンまで取り込まずに、劣化したウィンドウ内で通常より明らかに遅いスパンだけを切り出せます。
ヒートマップの下にある属性バーは、差異が大きいものから順に並んでいます。この例では、最上段のグラフが最も強いシグナルを示しています。SpanKind、SpanName、ScopeName はいずれも、遅い Selection と健全な Background の間で、オレンジと緑の鮮明な分離を示しています。これらを合わせて見ると、変曲点で何が変わったのかを特徴づけられます。
これは、「何が変わったのか」を知りたいときに適した形です。より絞り込んだパターンでも、同じ手順を使います。静かな帯の中に遅いスパンの小さな塊がある場合 (右端の短いバーストや、安定した期間の途中にあるクラスターなど) は、そのクラスターだけを囲む小さなボックスを描いてください。形によって、問いの立て方が変わります。縦長の帯は 時間の中で何が変わったか を問います。小さく絞ったボックスは このクラスターに特有なのは何か を問います。
ユースケース 2: 遅いものと速いもの
ヒートマップで、Duration 軸上に明確に分離した 2 つのレイテンシ集団が見えている場合は、時間範囲全体にまたがりつつ、上側のはっきり分離した帯だけを含むように広めの長方形をドラッグします。遅い集団が Selection になり、速い大多数が Background になります。
長方形は上側の帯をきっちり囲み、その帯と高密度の大きな集団の間に水平の隙間が見えるようにしてください。速い集団にはみ出すような緩い長方形にすると、差異が薄れてしまいます。
100 s の上限線自体も有益な手がかりです。切りのよい値で一定の水平線が現れるのは、固定タイムアウトの典型的な兆候です。2 つの集団を明確に区別できる span 属性が見つからない場合も、それは有用な結果です。その場合は、span 属性ではなく、ホストレベルやランタイムレベルのメトリクス (GC 停止、I/O 競合、スケジューラ遅延、コールドキャッシュの影響、ノイジーネイバー) を確認すべきことを示しています。
これは、特定の異常を追うのではなく、「遅い スパン は速い スパン と何が違うのか」を確認したいときに適したパターンです。差が現れる属性はコードパスや入力に原因があることを示し、差が出ない比較はシステム全体に原因があることを示します。
反復的なドリルダウン
比較モードと分布モードは、組み合わせて使うと最も効果を発揮します。いずれかのバーをクリックすると、3 つのアクションを含むポップオーバーが開きます。
- Filter: この値を持つスパンだけを残します
- Exclude: この値を持つスパンを除外します
- Copy: 値をクリップボードにコピーします
Filter または Exclude を適用すると、ヒートマップの選択はクリアされ、ヒートマップは新しい母集団に対して再描画され、分布モードはそのフィルタ済みの集合を対象に再開されます。ヒートマップの形がどう変わるかを確認してください。フィルタが成功すると、遅い帯域が目に見えて消えたり、二峰性の分離が縮小したり、右上がりの傾向が平坦になったりします。これを繰り返します。次に疑わしい値を見つけてフィルタし、新しいヒートマップを見て、新しい分布を確認します。通常は数回繰り返すだけで、回帰の原因を 1 つか 2 つの属性に絞り込めます。
低頻度の値をまとめた集約済みの Other (N) バケットはクリックできません。そのバケット内の特定の値でフィルタするには、検索バー を直接使用してください。
母集団が十分に小さくなったら、Results Table タブに切り替えて個々のトレースを確認します。フィルタはそのまま引き継がれます。
ヒートマップをカスタマイズする
ヒートマップ右上の歯車アイコンをクリックすると、Display Settings ドロワーが開きます。
| パラメーター | デフォルト | 説明 |
|---|---|---|
| Scale | Log | Log は遅延の広い範囲を扱うのに適しています。Linear は、範囲が狭く均一な分布に適しています。 |
| Value | (Duration)/1e6 | 任意の数値式です。レスポンスサイズ、エラー率、カスタムの スパン属性などを指定できます。 |
| Count | count() | 色分けに使用する集計です。avg()、sum()、p95()、または countDistinct(field) のような式に切り替えられます。 |
Apply をクリックするとヒートマップが更新され、下部の属性分析にも反映されます。
同じヒートマップは ダッシュボードタイル としても利用できます。これは、イベントデルタのドリルダウンフロー以外で、時間の経過に伴う分布の形状を監視したい場合に役立ちます。
これらのデフォルト値を変更する一般的なシナリオは次のとおりです。
- 遅延の範囲が狭い場合は、Scale を Linear に切り替えます (たとえば、すべてのスパンが 5〜50 ms の間に収まるサービスなど) 。Log スケールでは、データが存在しない上側の領域に縦方向の範囲が無駄に使われます。
- Y 軸に Duration 以外をプロットします。 Value を
SpanAttributes.http.response.sizeに設定すると、遅くてサイズの大きいレスポンスを調査できます。if(StatusCode = 'Error', 1, 0)のような式を使うと、サービス全体でのエラー頻度の時間変化をプロットできます。 - count 以外で色分けします。 Count を
p95(Duration)に設定すると、各 バケット は件数ではなくテールレイテンシで色分けされるため、件数ベースの表示では埋もれてしまう、まれだが遅い領域が浮かび上がります。countDistinct(TraceId)を使うと、1 つの trace が多数の spans を生成する場合に、trace の量と span の量を区別できます。
効果的に使うためのヒント
いくつかの実践を取り入れると、イベントデルタ は格段に活用しやすくなります。
- まず 1 つのサービスに絞り込みます。 レイテンシはサービスごとに大きく異なるため、複数を混在させるとシグナルが見えにくくなります。開始前に検索バーを使って 1 つの
ServiceName(または 1 つのエンドポイント) に絞り込み、ヒートマップと分布が比較可能な母集団を反映するようにします。 - 視覚的なコントラストがはっきりした選択範囲を選びます。 比較モードが最も効果を発揮するのは、Selection の帯が Background とはっきり区別できる場合です。たとえば、認識しやすい時点から始まる劣化期間や、大部分から明確に分離された低速な裾などです。残りのデータと大きく重なる選択範囲では、実際の差異ではなくノイズが目立ちやすくなります。
- 絞り込み、ヒートマップ、さらに絞り込み、を繰り返します。 1 回の選択だけで原因を特定できることはほとんどありません。最初の比較は仮説として扱い、最も乖離の大きい値で絞り込み、新しいヒートマップと分布を読み直します。通常は 2 ～ 3 回繰り返すことで、回帰を 1 つか 2 つの属性まで絞り込めます。
- まだコントラストが見えない場合は、選択範囲を作らずに 分布モード を使用します (問題があることは分かっていても、ヒートマップが一様に見える場合) 。エラー スパンのみ、クライアント スパンのみ、または 1 つのエンドポイントのみ、といった仮説ベースの絞り込みを適用し、長方形を描く前に属性分布から影響の大きい値を特定します。
トラブルシューティング
イベントデルタ タブが表示されない
Analysis Mode の イベントデルタ タブは、duration 式を持つ Trace ソースを選択した場合にのみ表示されます。データソースが Trace タイプとして設定されており、duration 情報を含むスパンデータがあることを確認してください。
属性チャートにほとんど、またはまったく結果が表示されない
サンプル数が少なすぎる場合 (スパンが数十件未満) 、分布に統計的な意味がないことがあります。タイムレンジを広げるか、検索フィルターを緩めてください。
