> ## 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 による異常検知アラート

> ClickStack の異常検知を使用すると、固定のしきい値を設定しなくても、メトリクスが想定される範囲から外れたときにアラートを送信できます。

> [!NOTE]
>
> **ベータ: Managed ClickStack のみ**
>
> 異常検知アラートはベータ版の機能で、Managed ClickStack でご利用いただけます。ClickStack Open Source では利用できません。ベータ期間中は、動作やデフォルト設定が変更される可能性があります。

異常検知アラートは、値が固定の数値を超えたときではなく、想定される範囲から外れたときに通知します。ClickStack は系列の直近の履歴から想定範囲を学習するため、サービスごとに「エラーが多すぎる」「遅すぎる」の基準をあらかじめ把握しておく必要はありません。

異常検知は、次のような場合に使用します。

* 適切なしきい値がサービス、エンドポイント、顧客ごとに異なり、その次元でアラートをグループ化する場合。
* 通常時の値が 1 日の中で変動するため、固定のしきい値ではピーク時に誤検知が多発するか、オフピーク時に異常を見逃してしまう場合。
* 絶対的な水準よりも、エラーの急増、レイテンシの急上昇、トラフィックがゼロに落ち込むといった急激な変化を重視する場合。

「p99 レイテンシが 2 秒を超える」「支払い失敗が 1 件でも発生する」など、常に適用したいハードリミットがある場合は、[静的しきい値アラート](https://clickhouse.com/docs/ja/clickstack/features/alerts.md)を使用してください。

## サポートされているアラート

異常検知は既存のアラートで選択できる検知モードの1つであり、独立したアラートの種類ではありません。次のアラートで利用できます。

* [検索アラート](https://clickhouse.com/docs/ja/clickstack/features/alerts.md#search-alerts)：一致したイベントの件数をスコアリングします。
* [ダッシュボードチャートアラート](https://clickhouse.com/docs/ja/clickstack/features/alerts.md#dashboard-alerts)：チャートビルダーで作成したチャートが対象です。

異常検知は [SQL ベースのチャートアラート](https://clickhouse.com/docs/ja/clickstack/features/alerts.md#sql-based-alerts) では利用できません。異常検知アラートを設定したチャートを SQL モードに切り替えると、ClickStack はそのアラートを静的しきい値アラートに変換します。異常検知を引き続き使用するには、チャートをビルダーに戻してください。

## 異常検知アラートの作成

**1. アラートエディタを開く**

[アラート](https://clickhouse.com/docs/ja/clickstack/features/alerts.md#types-of-alerts)で説明しているとおり、保存済み検索またはダッシュボードチャートのアラートエディタを開きます。

**2. 異常検知を選択する**

**Alert type** で **Anomaly detection** を選択します。デフォルトは **Static threshold** です。

**3. 条件を設定する**

条件は 1 つの文として読める形式になっています: **Alert when z-score is at least** `3` **when value is** `outside expected range` **compared to the past** `2 hours` **checked every** `5 minute`。

![アラートタイプとして異常検知が選択され、zスコア、方向、ベースライン、インターバルの各コントロール、平易な言葉による概要、バックテスト結果が表示された画面](https://mintcdn.com/private-7c7dfe99/tO1id1nFIHrN57gK/images/clickstack/anomaly-detection/anomaly-alert-condition.webp?fit=max\&auto=format\&n=tO1id1nFIHrN57gK\&q=85\&s=d5e50408b2af2de671c068ecfaef0bd8)

* **z-score is at least** (デフォルト `3`) : 値を異常とみなすために、期待値から何標準偏差離れている必要があるかを指定します。最小値は 0.5 で、矢印を使うと 0.5 刻みで変更できます。値が小さいほど感度が高くなり、発火の頻度も上がります。
* **When value is** (デフォルト `outside expected range`) : アラートの対象とする方向を `above expected`、`below expected`、`outside expected range` から指定します。エラー数やレイテンシには `above expected` を、スループットやサインアップ数には `below expected` を使用してください。
* **Compared to the past** (デフォルト 2 時間) : ClickStack が通常の変動を測定するために使用する履歴の長さを、30 分、または 1、2、4、6、12、24 時間から指定します。ベースラインを長くすると範囲は安定しますが、新たな平常状態への追従は遅くなります。
* **Checked every** (デフォルト 5 分) : アラートを評価する頻度を、5 分、15 分、30 分、または 1 時間から指定します。異常検知アラートでは、これより短いインターバルや長いインターバルは使用できません。

条件の下には、アラートの動作の要約が ClickStack によって表示されます。例: 「Every 5 minutes, values are compared to their typical range from the past 2 hours. Notifies when values rise above the expected range, once per incident.」

> [!TIP]
>
> スパイクの多い系列では、`outside expected range` よりも `above expected` または `below expected` を使用することを推奨します。短いスパイクの後は期待値の追従が遅れ、数分間高いままになるため、平常値への復帰も異常と判定される場合があります。`outside expected range` を使用すると、1 回のスパイクで 2 回通知されることがあります。

**4. バックテストとプレビューを確認する**

概要の下に表示される行はバックテストの結果です。現在の設定を直近の履歴に再適用し、アラートが何回通知していたかを示します。例: 「Would have notified 6 times in the past 24 hours, firing on 12 of 288 checks.」検索アラートの場合、バックテストの対象は過去 24 時間です。ダッシュボードチャートアラートの場合は、チャートで選択された時間範囲 (最大 24 時間) が対象になります。通知が 1 日 10 回を超える見込みの場合、回数は黄色で表示されます。

フォームの下にある **Anomaly detection chart** には、同じ範囲がプロットされます。

* 実線は系列です。
* 破線は期待されるベースラインです。
* 網掛け部分はアラートのトリガーゾーンです。値が期待範囲を超えてこの領域に入ると発火します。
* **Notify** マーカーは、アラートが通知を送信していたはずの位置を示します。

![24時間分の系列、期待されるベースライン、網掛けのアラートトリガーゾーン、6つのスパイクそれぞれにNotifyマーカーを表示した異常検知チャート](https://mintcdn.com/private-7c7dfe99/tO1id1nFIHrN57gK/images/clickstack/anomaly-detection/anomaly-alert-preview.webp?fit=max\&auto=format\&n=tO1id1nFIHrN57gK\&q=85\&s=95ec50b0c758ba0d32e33a222451c80c)

アラートがグループ化されている場合、バックテストではすべての系列の通知回数が合計されます。**Show breakdown by series** を選択すると、どの系列で最も多く通知が発生していたかを確認できます。以下の例では、1 つのスパースな系列が通知の 40% 以上を占めているため、その系列を除外するか、個別にアラートを設定することを検討するとよいでしょう。

![グループ化された異常検知アラートについて、サービスごとの通知エピソードを一覧表示したバックテストの内訳](https://mintcdn.com/private-7c7dfe99/tO1id1nFIHrN57gK/images/clickstack/anomaly-detection/anomaly-backtest-breakdown.webp?fit=max\&auto=format\&n=tO1id1nFIHrN57gK\&q=85\&s=7d431d47d52363c6fd6b7051ab06179f)

バックテストの結果が、通知を受けたい内容と一致するまで zスコア、方向、ベースラインを調整してください。1 日に何度も通知される場合は、zスコアを上げるか、方向を絞り込んでください。

**5. 通知チャネルを選択して保存する**

他のアラートと同様に、Webhook またはその他のチャネルを選択します。[Webhook の追加](https://clickhouse.com/docs/ja/clickstack/features/alerts.md#add-webhook)を参照してください。アラートを保存すると評価が開始されます。

### 適合性に関する警告

系列によっては、異常検知に適さないものがあります。その場合、保存前にプレビューチャートの下に警告が表示されますが、保存自体は妨げられません。

| 警告 | 原因 | 対処方法 |
| - | - | - |
| ベースラインに必要な履歴がまだ不足しています | 系列が新しいか、プレビュー範囲の大部分にベースラインデータがありません。 | データが蓄積されるまで待つか、履歴が揃うまでは静的しきい値を使用してください。 |
| ほとんどの時間バケットが空です | 系列に初めてデータが記録されて以降、半分以上の分が空になっています (目安として 1 分あたり 1 イベント未満) 。 | 検索条件を広げる、group-by を削除する、または静的しきい値を使用してください。 |
| この系列はほぼフラットです | 系列の変動がほとんどないため、わずかな揺らぎでも極端な z スコアが生じます。 | 静的しきい値を使用するか、z スコアを引き上げてください。 |

![ほとんどの時間バケットが空であるという警告が表示された、スパースな系列の異常検知チャート](https://mintcdn.com/private-7c7dfe99/tO1id1nFIHrN57gK/images/clickstack/anomaly-detection/anomaly-suitability-warning.webp?fit=max\&auto=format\&n=tO1id1nFIHrN57gK\&q=85\&s=f3b1dcb697b88b8901e7421855b9865b)

## 異常検知の仕組み

評価のたびに、ClickStack は評価ウィンドウをバケットごとに 1 つずつスコアリングします。バケットの長さは 60 秒です。

各バケットでは、次の処理が行われます。

1. **期待値。** ClickStack は、1 評価ウィンドウ分前の時点までに終了した 7 つのバケットの移動平均を求めます。期待値が負になることはありません。
2. **ばらつき。** ClickStack は、**Compared to the past** で選択したベースライン期間における系列の標準偏差を ClickHouse 上で計算します。ベースラインが 1 評価ウィンドウより短くなることはありません。
3. **z スコア。** z スコアは `(value − expected) / standard deviation` で算出されます。
4. **判定。** z スコアが設定済みの方向で設定済みのしきい値を超え、かつ値と期待値の差が期待値の 5% 以上 (期待値が 0 の場合は 0.01 以上) であるとき、そのバケットは発報します。この 5% の下限により、ほぼ一定の系列がわずかな揺らぎで発報するのを防ぎます。

期待範囲は `expected ± z-score × standard deviation` に 5% の下限分の幅を加えたものです。プレビューでは、この範囲外の領域がすべてアラートのトリガーゾーンとして網掛け表示されます。

評価ウィンドウ内のいずれかのバケットが発報すると、その評価ウィンドウが発報します。

### 空のバケット

ClickStack がデータのない1分間をどう扱うかは、集約の種類によって異なります。

* **カウントと合計** (検索アラートを含む) : 空のバケットはゼロとしてスコア付けされます。そのため、方向が `below expected` または `outside expected range` のアラートは、トラフィックが完全に途絶えると発報します。
* **平均、パーセンタイル、最小値、最大値、比率、およびメトリクスソース**: 空のバケットは測定対象がなかったことを意味するため、ゼロとしてスコア付けされず、スキップされます。

十分な履歴がないバケットはスコア付けされないため、新しい系列はベースラインが確立されるまで発報しません。

### グループ化されたアラート

アラートが `ServiceName` などのフィールドでグループ化されている場合、各グループはそれぞれ独自の想定範囲とアラート状態を持つ個別の系列として扱われます。ClickStack は 1 つのアラートにつき最大 100 個の系列をスコアリングし、データ量の多い系列を優先します。すでにアラート状態にある系列は、上位 100 個から外れた場合でも、解消されるまでスコアリングが継続されます。

### 通知と解決

異常検知アラートの通知は、インシデントごと・系列ごとに1回だけ送信されます。

* 系列が発火し始めると、ClickStack は通知を1回送信し、その系列をアラート中としてマークします。
* 以降の評価でも系列が発火し続けている間は、追加の通知は送信されません。
* 評価ウィンドウ内に発火したバケットがなくなると、系列は解決済みとなり、ClickStack は解決通知を送信します。

障害時などに複数回の評価が実行されなかった場合は、次回の評価で未評価のウィンドウをまとめて処理します。その場合でも、発火通知は系列ごとに最大1回しか送信されません。

ClickStack はウィンドウが閉じてから30秒待って評価を行うため、遅れて到着したデータも集計対象になります。

通知には、しきい値ではなく異常の内容が記載されます。例:

* タイトル: `Alert for "Checkout errors" - value 142 is above the expected range (z-score 4.4)`
* 本文: `Value 142 is above the expected range — z-score 4.4 vs sensitivity 3; expected 120 ± 5 (expected range 105 to 135).`

カスタムのアラート名やメッセージでは、`{{anomaly.value}}`、`{{anomaly.expectedValue}}`、`{{anomaly.expectedStddev}}`、`{{anomaly.lowerBound}}`、`{{anomaly.upperBound}}`、`{{anomaly.zScore}}` を使用して、通知をトリガーしたバケットの値を参照できます。これらの値が設定されるのは発火通知のみで、解決通知には含まれません。そのため、同じ名前やメッセージを両方の通知で使用する場合は、`{{#if anomaly}}...{{/if}}` で囲んでください。

## 異常検知アラートの監視

**Alerts** ページで **Filter by type** を **Anomaly** に設定すると、異常検知アラートのみが表示されます。各行には条件が表示されます (例: 「If value is above expected with z-score at least 3」) 。

![異常検知アラートでフィルタされた Alerts ページ。1 件のアラートとその条件、直近の評価履歴が表示されている](https://mintcdn.com/private-7c7dfe99/tO1id1nFIHrN57gK/images/clickstack/anomaly-detection/anomaly-alerts-list.webp?fit=max\&auto=format\&n=tO1id1nFIHrN57gK\&q=85\&s=fb42a360ae87aa848b0df89586c3ba1c)

アラートを選択すると、その詳細ページが開きます。時間間隔とベースラインを含む条件の概要の下に、保持されている履歴期間内でアラートが発火した回数が表示されます (例: 「Fired 2 times in the past 2 days.」) 。この範囲を選択すると、その期間がチャートと評価履歴に反映されます。

![条件の概要と、過去 2 日間にアラートが発火した回数を表示している異常検知アラートの詳細ページ](https://mintcdn.com/private-7c7dfe99/tO1id1nFIHrN57gK/images/clickstack/anomaly-detection/anomaly-alert-detail.webp?fit=max\&auto=format\&n=tO1id1nFIHrN57gK\&q=85\&s=08a49875dd775655326c8c71aa2fbdda)

**Evaluation History** テーブルには、各チェックのステート、最新の値、およびアラート状態にあった系列の数が一覧表示されます。通知の所要時間が記録されている行は、通知が送信されたことを示します。通知はアラートの発火時と解決時の両方で送信されます。

![5 分ごとのチェックについて Alert および Ok のステートを示す異常検知アラートの評価履歴](https://mintcdn.com/private-7c7dfe99/tO1id1nFIHrN57gK/images/clickstack/anomaly-detection/anomaly-alert-history.webp?fit=max\&auto=format\&n=tO1id1nFIHrN57gK\&q=85\&s=8c1e4245bc062d4203c30ef2ae87975d)

アラートが 20 ウィンドウ以上連続してアラート状態のままの場合、詳細ページには、その系列は異常ではなく新たな通常状態に移行している可能性がある旨が表示されます。z-score を引き上げるか、より適切なベースラインと比較するようにアラートを更新してください。

## MCP によるバックテスト

[ClickStack MCPサーバー](https://clickhouse.com/docs/ja/clickstack/mcp.md) を使用すると、異常検知の設定を保存する前に、AIアシスタントにバックテストを実行させることができます。`clickstack_backtest_anomaly_alert` ツールは、最大 24 時間分の履歴データに対して設定を再適用し、その設定で送信されていたはずの通知を系列ごとに、データ品質に関する警告とあわせて報告します。このツールは読み取り専用です。

## チューニングのヒント

* **アラートのノイズが多すぎる場合:** z スコアを 0.5 刻みで引き上げるか、方向を `outside expected range` から注目したい側に変更します。
* **アラートが実際のインシデントを見逃した場合:** z スコアを引き下げるか、ベースラインを短くして、範囲に直近の挙動が反映されるようにします。
* **デプロイ後にアラートが一日中発報し続ける場合:** 系列の平常状態が変化しています。ベースラインが長いほど、新しい状態に適応するまでに時間がかかります。
* **データ量が少ない系列の場合:** グループ化する次元を減らすか、より広い検索条件でアラートを設定して、各系列で 1 分あたり少なくとも 1 件のイベントが発生するようにします。
