> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# ClickStack のイベントデルタ
> ClickStack のイベントデルタを使って、トレース属性の分布を分析し、外れ値のスパンを比較します
export const Image = ({img, alt, size}) => {
return
;
};
イベントデルタでは、レイテンシヒートマップと属性の自動分析を組み合わせることで、クエリを書かなくてもトレースデータの傾向を把握し、遅いスパンがなぜ異なるのかを特定できます。使い方は 3 つあります。
* **分布モード (常時有効) **: ヒートマップ上で選択範囲がない場合、現在のスパン集団における各属性の値の分布が表示されます。支配的な値や、異常にまれな値 (カーディナリティの外れ値) を見つけるのに役立ちます。
* **比較モード**: ヒートマップ上で長方形をドラッグすると、その内側のスパン (Selection) と外側のすべて (Background) を比較できます。偏りや逸脱の切り分けに役立ちます。
* **反復的ドリルダウン**: 任意のバーをクリックすると、その値で絞り込み (または除外) できます。ヒートマップは絞り込み後の集団に対して再描画されるため、原因が明らかになるまでさらに絞り込めます。
上のスクリーンショットでは、ヒートマップの右端は、午前中ずっと維持されていた 1 ms のベースラインには戻らず、およそ 10 ms に達しています。劣化はまだ進行中で、インシデントのただ中を捉えています。
## 前提条件
イベントデルタには、duration 式を持つ **Trace** データソースが必要です。スパン データを生成する、OpenTelemetry でインストルメントされた任意のサービスで使用できます。すべての ClickStack のデプロイ形態 (Managed、Open Source、ClickHouse Cloud) で利用できます。
## はじめに
1. **Data Source** ドロップダウンから、トレースを保持しているログソースを選択します。ログソース名は任意ですが、重要なのは、そのログソースが Trace タイプとして設定されていることです。**イベントデルタ** タブは、そのようなログソースでのみ有効です。
2. **Analysis Mode** セクションで、**イベントデルタ** タブをクリックします。
イベントデルタは、**Results Table** や **イベントパターン** と並ぶ独立した分析モードです。これに切り替えると、表示はヒートマップと属性分析グリッドに切り替わりますが、検索フィルタと時間範囲は保持されるため、いつでも元に戻せます。
## ヒートマップ
ヒートマップでは、スパンを 2 つの次元でプロットします。
* **X axis**: 時間
* **Y axis**: 数値 (既定ではスパンの継続時間 (ミリ秒、対数スケール) )
色の濃さはバケットごとのイベント数を表し、明るいほどスパン数が多いことを示します。
ヒートマップを見ると、パターンをそのまま読み取れます。たとえば、二峰性のレイテンシ、特定の時刻に発生するレイテンシのスパイク、常に低速なスパンの帯、あるいは時間の経過とともに上方へずれていく低速な帯 (徐々に進行する性能劣化) などです。特定の領域を調査するには、その上でクリックしてドラッグし、長方形を描きます。するとそれが **Selection** となり、下の分析は比較モードに切り替わります。
## 分布モード: カーディナリティの外れ値
ヒートマップで何も選択していない場合、分析パネルには属性ごとに1つの棒グラフが表示され、一致するすべてのスパンを対象に集計されます。凡例には **All spans** と表示されます (上の概要のスクリーンショットを参照) 。
属性は、値の集中度に基づいて順位付けされます。少数の値に偏っている属性ほど上位に表示され、均一でエントロピーの高い属性は優先度が下がります。
データの**カーディナリティの傾向**を把握したい場合は、分布モードを使用します。
* **高頻度**: どのサービス、エンドポイント、ステータスコード、またはホストがスパン全体の大半を占めているでしょうか。多くの場合、トラフィックの大部分を占める単一のテナント、バージョン、またはルートが浮かび上がります。
* **低頻度**: 出現はするものの、まれな値です。`0.5%` のスパンにしか現れないステータスコードや、ほとんど現れないホストは、むしろ最も興味深いシグナルかもしれません。回帰や問題のある要因は、このロングテールに潜んでいます。
まず検索バーと組み合わせて対象を絞り込み (たとえばエラースパンのみ、クライアントスパンのみ、1つのエンドポイントのみ) 、そのうえでそのサブセットの分布を確認してください。
## 比較モード: 通常状態からの逸脱
ヒートマップ上で長方形をクリック＆ドラッグすると、比較モードに入ります。選択したスパンは **Selection** (オレンジのバー) となり、その外側のすべては **Background** (緑のバー) となります。各属性チャートには両方の集団が並べて表示され、差異が最も大きい属性が先頭に来るようにソートされます。片方にのみほぼ存在する値、または片方には存在しない値が、何が異なるのかを示す最も有力な候補です。
どのような長方形を描くかによって、何を比較しようとしているのかが変わります。一般的な形は次の 2 つです。
### ユースケース 1: 回帰の前後
ヒートマップで、時間の経過とともにレイテンシが上方へずれていく様子が見える場合 (遅い帯が厚くなる、明るい帯が上にせり上がる、あるいは正常な期間と劣化した期間の境目に明確な変曲点がある場合) は、その立ち上がりの変曲点から表示範囲の右端まで長方形をドラッグします。比較をより明確にするには、長方形の下端を軸の最下端ではなく正常時のベースラインに合わせてください。こうすることで、劣化した時間帯の中でも、実際に通常より遅いスパンだけを切り出せます。同じ時間範囲に含まれているだけの、まだ正常な高速スパンを拾わずに済みます。
ヒートマップの下にある属性バーは、差分が大きいものから順にソートされています。この例では、最上段のチャートが最も強いシグナルを示しています。`SpanKind`、`SpanName`、`ScopeName` はいずれも、遅い `Selection` と正常な `Background` の間で、オレンジと緑がくっきり分かれています。これらを合わせて見ると、変曲点で何が変わったのかを特定できます。
これは、「何が変わったのか？」を知りたいときに適した形です。より絞り込んだバリエーションでも、同じ手順を使えます。静かな帯の中に遅いスパンの小さな塊がある場合 (右端の短いバーストや、安定した期間の途中にあるクラスターなど) は、そのクラスターだけを小さなボックスで囲んでください。形が変われば、問いも変わります。縦長の帯は *時間の中で何が変わったか* を問い、小さく絞ったボックスは *このクラスターに特有なのは何か* を問います。
### ユースケース 2: 遅いものと速いもの
ヒートマップで、duration 軸上にはっきり分離した 2 つのレイテンシ集団が見えている場合は、時間範囲全体にまたがりつつ、上側の明確に分離された帯だけを含む幅広い長方形をドラッグします。遅い集団が Selection になり、速い大半が Background になります。
長方形は上側の帯をぴったり囲むように描き、その帯と密集した大部分の間に、水平の隙間がはっきり見えるようにしてください。速い集団にはみ出すような大まかな長方形だと、違いがぼやけてしまいます。
100 s の上限線は、それ自体が有益な手がかりです。切りのよい値に現れる一定の水平線は、固定 timeout の典型的な兆候です。2 つの集団を明確に分ける スパン attribute が見つからない場合も、それは有用な結果です。その場合、原因は スパン attribute ではなく、ホストレベルや runtime レベルのメトリクス (GC pause、I/O 競合、scheduler latency、cold-cache の影響、noisy neighbor) にあることを示唆します。
これは、特定の異常を追いかけるのではなく、「遅い スパンs は速い スパンs と何が違うのか」を知りたいときに適した形です。違いのある attribute はコードパスや入力要因を示し、差が出ない比較はシステム全体の要因を示します。
## 段階的なドリルダウン
比較モードと分布モードは、組み合わせて使うと真価を発揮します。任意のバーをクリックすると、3 つのアクションを含むポップオーバーが表示されます。
* **Filter**: この値を持つ スパン のみを残します
* **Exclude**: この値を持つ スパン を除外します
* **Copy**: 値をクリップボードにコピーします
filter または exclude を適用すると、ヒートマップの選択はクリアされ、ヒートマップは新しい母集団に対して再描画され、分布モードはそのフィルタ済みのセットを対象に再開されます。ヒートマップの形がどう変わるかを確認してください。filter がうまく機能すると、遅い帯域が目に見えて消えたり、二峰性の分離が収束したり、右肩上がりの傾向が平坦になったりします。これを繰り返します。次に疑わしい値を見つけて filter し、新しいヒートマップを見て、新しい分布を確認します。通常は数回繰り返すだけで、リグレッションの原因を 1 つか 2 つの attribute に絞り込めます。
出現頻度の低い値をまとめた集計 **Other (N)** バケットはクリックできません。そのバケット内の特定の値でフィルタするには、[検索バー](/ja/clickstack/features/search) を直接使用してください。
母集団が十分に小さくなったら、**Results Table** タブに切り替えて個々の traces を確認します。フィルタはそのまま引き継がれます。
## ヒートマップをカスタマイズする
ヒートマップ右上の歯車アイコンをクリックすると、**表示設定**ドロワーが開きます。
| パラメーター | デフォルト | 説明 |
| --------- | ---------------- | --------------------------------------------------------------------------------------------------- |
| **Scale** | Log | Log は広い latency の範囲に適しています。狭く uniform な分布には Linear のほうが適しています。 |
| **Value** | `(Duration)/1e6` | レスポンスサイズ、エラー率、カスタムの スパン attribute など、任意の数値 expression を指定できます。 |
| **Count** | `count()` | 色分けに使う aggregation です。`avg()`、`sum()`、`p95()`、または `countDistinct(field)` のような expression に切り替えられます。 |
ヒートマップを更新するには **Apply** をクリックします。下の attribute 分析もそれに合わせて更新されます。
**ダッシュボード上のヒートマップ**
同じヒートマップは [dashboard tile](/ja/clickstack/features/dashboards/overview#create-a-tile-heatmap) としても利用できます。イベントデルタ の ドリルダウン フローの外で、時間の経過に伴う distribution の形状を監視したい場合に便利です。
これらのデフォルト値を変更したくなる一般的なケースは次のとおりです。
* latency の範囲が狭い場合 (たとえば、すべての スパンs が 5～50 ms で実行される service) には、**Scale を Linear に切り替えます**。Log スケールでは、データが存在しない上側の領域に縦方向の表示範囲が無駄に使われます。
* **Y 軸に Duration 以外をプロットします。** **Value** を `SpanAttributes.http.response.size` に設定すると、低速で*サイズの大きい*レスポンスを調査できます。`if(StatusCode = 'Error', 1, 0)` のような expression を使うと、services 全体にわたる時間経過ごとのエラー頻度をプロットできます。
* **count 以外で色分けします。** **Count** を `p95(Duration)` に設定すると、各 bucket は件数ではなく tail latency に応じて色分けされるため、count ベースのビューでは埋もれてしまう、まれでも低速な領域を浮かび上がらせることができます。`countDistinct(TraceId)` を使うと、1 つの trace が多数の スパンs を生成する場合に、trace volume と span volume を区別できます。
## 効果的に使うためのヒント
いくつかのポイントを押さえると、イベントデルタをより効果的に活用できます。
* **まずは 1 つのサービスに絞り込みます。** レイテンシはサービスごとに大きく異なるため、複数を混在させるとシグナルが埋もれてしまいます。作業を始める前に検索バーで 1 つの `ServiceName` (または 1 つのエンドポイント) に絞り込み、ヒートマップと分布が比較可能な母集団を反映するようにします。
* **視覚的なコントラストが明確な Selection を選びます。** 比較モードは、Selection の帯が Background とはっきり区別できるときに最も効果を発揮します。たとえば、はっきりした時点から始まる性能劣化の期間や、大半のデータから明確に分離した遅いテールなどです。残りのデータと大きく重なる Selection では、実際の差異ではなくノイズが目立ちやすくなります。
* **filter、heatmap、filter の順で繰り返します。** 1 回の Selection だけで原因を特定できることはほとんどありません。最初の比較は仮説と捉え、最も差が大きい値で filter し、更新されたヒートマップと分布を再確認します。通常は 2 ～ 3 回繰り返すことで、リグレッションの原因を 1 ～ 2 個の属性まで絞り込めます。
* **まだコントラストが見えない場合は、Selection なしで分布モードを使います** (問題があることはわかっていても、ヒートマップが均一に見える場合) 。error スパンs のみ、client スパンs のみ、または 1 つのエンドポイントのみに絞るといった仮説ベースの filter を適用し、長方形を描く前に、属性の分布から影響の大きい値を見つけます。
## トラブルシューティング
### イベントデルタ タブが表示されない
**Analysis Mode** の **イベントデルタ** タブは、duration 式を持つ **Trace** ログソースが選択されている場合にのみ表示されます。データソースが **Trace** タイプとして設定されており、duration 情報を含む スパン データが存在することを確認してください。
### 属性チャートの結果がほとんど、またはまったく表示されない場合
サンプル数が少なすぎる場合 (スパンが数十件未満の場合) 、分布には統計的な意味がないことがあります。時間範囲を広げるか、検索フィルタを緩めてください。