アラート

Yagra はアラートの品質を最優先に設計しています。目的はアラートを送ることではなく、正しいアラートを送ることです — 本当のインシデント 1 件につき呼び出しは 1 回、拠点が落ちても洪水にはならず、メトリクスが 1 サンプルだけしきい値をかすめたくらいで午前 3 時に鳴ることもない。そういう状態を目指しています。ヒステリシス、フラッピング検知、依存関係の抑制、重複排除は、つねに配信経路の中にあります — あとから有効にする追加機能ではありませんし、「とにかくアラートを送る」ためにこれらを迂回する手段もありません。

エスカレーションとオンコールのスケジューリングは、意図的に外部ツール（PagerDuty、Jira Service Management）へ委譲しています。Yagra は発報と解消というライフサイクルの信号を素直に出すだけで、自前のエスカレーションスケジューラは持ちません。

アラートのライフサイクル

アラートを発報させるものは 3 つあります。

死活の失敗 — デバイスが ICMP プローブに応答しなくなる（あるいは URL / DNS モニタが成功しなくなる）。
しきい値の超過 — ゲージメトリクスがルールの warning または critical の境界を越える（しきい値のモデルは監視を参照）。
イベントルールの一致 — パッシブイベント（syslog、トラップ、Webhook）がオペレーターの定義したルールに一致する（後述のイベント由来のアラートを参照）。

きっかけが何であれ、すべてのノードのすべてのチェックは確定した状態を持ちます。

状態	意味
`ok`	チェックは正常です
`warning`	しきい値ルールの warning 境界を超えています
`critical`	しきい値ルールの critical 境界を超えています
`unreachable`	死活が失敗しています — ノードが応答しません
`unknown`	Yagra は現時点で判断を持っていません（直近のサンプルがない）
`maintenance`	ノードがメンテナンスウィンドウの中にあります

問題状態 — warning、critical、unreachable — だけが重大度を持ち、アラートを生みます。ok、 unknown、maintenance が生むことはありません。まだ見えていないノードや計画作業中のノードは、インシデントではないからです。（新しく追加したノードやコアの再起動直後には、アラートエンジンがすべてのノードについて判断を形成するまでのあいだ unknown が短時間見えます — サンプルが届けば自然に解消します。）

アラートは、チェックが（後述のヒステリシスを経て）問題状態を確定したときに発報し、同じ経路を通ってチェックが回復したときに解消します。同じ問題の繰り返しの発報は重複排除され、重複の連なりとして配信されるのではなく 1 つのインシデントにまとめられます。発報と解消はすべて追記専用の アラート履歴に記録され、その原因となった測定値も発報時点の値のまま保存されます。

ドウェル時間によるヒステリシス

生のサンプルがしきい値を越えても、それだけで確定状態が切り替わることはありません。状態が確定してアラートが発報するには、超過が設定された連続サンプル数（ドウェル）だけ続く必要があります — そして確定状態へ戻るサンプルが 1 つでもあれば候補はリセットされ、途切れた連続はまた最初から数え直しになります。

これが、境界を一度かすめただけのメトリクスや 1 回の ping 欠落で誰かを呼び出さずに済む仕組みです。たとえばドウェルが 3 なら、そのノードのポーリング間隔で超過サンプルが 3 回連続することを意味します — 途中に回復サンプルが 1 つ入れば、カウントはやり直しです。

実時間ではなくサンプル数で数えることは、アーキテクチャにも影響します。アラートの評価はつねにライブのサンプルストリームに対して行われ、あとから補完された履歴（たとえばリモートポーラーが再接続してバッファを再生した場合）がアラートとして再評価されることはありません — ためこんだものを再生すれば、すでに解消したインシデントの遷移をでっち上げることになるからです。メトリクスは埋まり、アラートは現在から再開します。

フラッピング検知

数分おきに上下するリンクは、そのたびに技術的には正しいアラートを生みます — そしてその 1 本 1 本がノイズです。Yagra はスライディングウィンドウの中でチェックごとに確定状態の遷移回数を数え、ウィンドウ内で遷移のしきい値を超えたチェックには、その遷移についてフラッピングの印を付けます。

フラッピングしているチェックはダッシュボードウィジェットの Flapping watchlist に現れ、ノードの名前（id はホバーで表示）と、そのフラッピングしているチェックが何を測っているかを示します — おかげで不安定なリンクは、上下のたびに切り分けをやり直すのではなく、1 つの問題としてまとめて直せます。

さらに深く掘るために、Troubleshoot のカタログにはノード・グループ・フリート全体を対象に到達性とリンク状態の揺れを走査するフラップ分析があり、同じノードで発報と解消を繰り返しているイベントルールを見つける対の分析もあります。

依存関係抑制

拠点のルータが死ぬと、その背後にあるものはすべて見えなくなります — そして抑制がなければ、そのノードのひとつひとつがあなたを呼び出します。Yagra は依存関係グラフから抑制を駆動します。各ノードは自分の上流を指定でき、グラフは Network map 上で可視化されます。

ノードが unreachable になり、その上流の連なりもダウンしている場合、アラートはダウンしている最上位の祖先に — つまり根本原因に — 帰属させられ、その親のインシデントへまとめられます。子のアラート自体は発報し、UI にも履歴にも見えたままです。抑制されるのは重複した通知だけです。トポロジのビューと、依存関係／根本原因のダッシュボードウィジェットはこの帰属を表示するので、1 つのインシデントは影響範囲を伴う 1 つのインシデントとして読めます。

抑制は親の状態が変わるたびにイベント駆動で再評価されます — しかも双方向にです。

子がすでにアラートを上げたあとでダウンした親は、その既存のアラートを自分のインシデントの下へまとめ直します（子の単独の呼び出しは閉じられます）。
子がまだダウンしているうちに回復した親は、その子を単独で呼び出し直します — もはや親では説明がつかないからです。

抑制が嘘をつかないよう、意図的な制限を 2 つ設けています。

抑制されるのは死活アラートだけです。しきい値アラートは抑制しません。到達できるノードで本当にしきい値を超えているなら、それは呼び出されるに値するからです。
パッシブイベントから上がったアラートも抑制を通りません。イベントを出したばかりのデバイスは、明らかに到達可能だからです。

依存関係のエッジは WebUI から編集できます。ノード詳細のヘッダーにある Dependency… アクションでノードの上流を設定・解除でき、トポロジ ▸ 依存関係はすべてのノードを、その上流・現在の状態・現在の根本原因の帰属とともに一覧し、その場で編集できます。自己依存と循環は拒否されます。

Yagra にグラフを導出させる

ノードごとに上流を入力していく方式は規模に耐えず、誰も保守しなくなったグラフは間違ったものを抑制します。Yagra は依存関係グラフをネットワークマップから導出できます — 向きは各ノードのポーラーからの距離で決まり、1 ホップ近い側が上流になります。

トポロジ ▸ 依存関係に 3 段のモードスイッチがあります。位置が勝手に動くことはなく、アップグレードしても今のモードのままです:

手動作成のグラフ — 既定であり、既存のすべてのデプロイがここに留まります。
比較 — アラートの挙動は何も変えません。導出したグラフと手動のグラフがどこで食い違うかをノード単位で表示し、切り替えの安全性を判断する 2 つの数値を出します: 導出グラフが新たに抑制することになるアクティブアラート数（危険な方向 — 1 件ごとに上がらなくなるアラート）と、抑制をやめることになる数。
導出したグラフ — 抑制の判断を委ねます。

導出グラフが表現できて、手入力の parent_id には表現できないことが 2 つあります。ノードにはポーラーに 1 ホップ近い隣接すべてが親として付くため、冗長なルータ 2 台経由で到達するサーバーは両方を親に持ち、どちらかが生きている限りアラートを上げ続けます — 「すべての親が落ちたときだけ抑制する」という規則は元々このために書かれたものです。もう 1 つは、抑制しないを設定すれば、特定の 1 台を導出抑制から完全に外せることです。グラフが何と言おうと、そのノードのアラートは単独で立ちます。この設定は抑制を外す方向にしか働かないため、障害が報告されなくなる原因にはなりません。

導出が間違ったリンクを作った場合は、回避策ではなく判断を記録してください。リンクはピン留めして存在させる、非表示にする、どちらが上流かを宣言する、のいずれもでき、これらは再計算のたびに導出結果より優先されます。

メンテナンスウィンドウとミュート

計画された作業で誰かを呼び出すべきではありません。

メンテナンスウィンドウは予定された作業のためのものです。ウィンドウはノードに対して開かれ、開いているあいだノードは maintenance 状態に置かれます。この状態がアラートを生むことは決してありません。ウィンドウの開閉は Operator 以上の操作です（メンテナンス管理権限）。
ミュートはその場しのぎの形式です — 何も予定せずに、うるさいと分かっているアラートを黙らせます。ミュートは確認（ACK）と同じく、Operator ロールのインシデント対応権限に含まれます。

どちらも専用の設定ページを持ち、監査の対象になる正式な機能です — あとから通知に取って付けたフィルタではありません。

ルーティングと通知チャネル

アラートがヒステリシス・抑制・メンテナンスの各チェックを生き延びると、通知ルーティングがその行き先を決めます。Yagra が配信できるのは次のとおりです。

チャネル	備考
Webhook	汎用の HTTP Webhook。リトライあり
Email（SMTP）	リトライあり。リレー、送信者、認証情報を設定可能
PagerDuty	Events API v2
Jira Service Management	Alerts API

すべてのチャネルがライフサイクル全体 — 発報と解消の両方を受け取ります。そのため、Yagra のアラートが解消すれば外部ツール側のインシデントも閉じ、古いインシデントが残って手で片付ける羽目になることはありません。外部ツールで行われた確認（ACK）は、読み取り専用で Yagra に反映されます。どのチャネルへ通知するかはルーティングルールが選び、通知ルーティングの設定ページで管理します。

配信は結果の取り込み経路から切り離して動きます。遅い、あるいは応答しない通知先は自分の通知を遅らせることはあります（リトライします）が、その背後でメトリクスの取り込みやアラートの評価を止めてしまうことはありません。

外向きの Webhook は監視プローブと同じように SSRF から保護されています。ループバック、リンクローカル、クラウドメタデータ宛の対象は拒否されます。

通知テンプレート

チャネルごとに、送信する件名と本文を上書きできます。アラートの決まった変数集合（ノード名、アドレス、グループ、プロファイル、重大度、メトリクス、しきい値、観測値、発報か復旧か）に対する Jinja2 テンプレートとして書きます。条件分岐が使えるので、重大度やライフサイクルイベントごとに文面を変えられます:

{% if event == 'resolve' %}復旧{% else %}{{ severity | upper }}{% endif %}: {{ node_name }} ({{ group }})

テンプレートを設定していないチャネルは、Yagra の組み込みの文面をそのまま送信します。書く前に知っておくとよい性質が 2 つあります:

テンプレートが壊れていても通知は失われません。 アラート発報時にレンダリングできなかった場合 — 不正なフィルタ、出力が大きすぎる、JSON を送るチャネルで本文が有効な JSON でなくなったなど — そのフィールドは組み込みの文面にフォールバックし、通知自体は送信されます。フォールバックは単純な文字列置換であり、たった今失敗したエンジンをもう一度通すことはしません。
テンプレートはサンドボックス内で動きます。 テンプレートが触れるのは渡された変数だけです。ファイルも include も他のテンプレートも参照できません。実行ステップ数にも上限があるため、暴走ループが通知ワーカーを止めることはありません。

編集画面はアラート ▸ 通知ルーティング ▸ チャネル ▸ 通知テンプレートを編集にあります。変数パレットと、サンプルアラートに対するライブプレビューが付いています。

UI を触らずにデプロイ全体で固定の経路を持たせたい場合のために、環境変数レベルのチャネルが 2 つあります。YAGRA_WEBHOOK_URL は、設定済みのチャネルと並んですべてのアラートで発火する常時有効の既定 Webhook を定義し、YAGRA_SMTP_* 系の変数は既定のメール経路を定義します — 設定リファレンスを参照してください。

イベント由来のアラート

アラートはポーリングだけから来るわけではありません。パッシブイベント — syslog メッセージ、SNMP トラップ、受信 Webhook — はオペレーターが定義したイベントルール（部分一致または正規表現）で判定され、一致したルールはアラートを発報できます。受信した SNMP トラップはトラップ OID が人の読める名前に解決され、組み込みのトラップ用イベントルールも最初から同梱されているため、よくあるトラップは設定なしで名前付きのアラート可能なイベントとして届きます。取り込み側についてはパッシブイベントを参照してください。

イベント由来のアラートは、ポーリング由来のものと 2 つの点で異なります。

TTL で解消します。 単発のイベントには観測すべき「回復サンプル」がないため、各ルールが自動解消の TTL を持ちます。アラートは TTL が切れたときに閉じます（手動で閉じることはできません）。
依存関係抑制を通りません。 イベントを出したばかりのデバイスは到達可能なので、「ダウンしている」親の下でそのアラートを抑制するのは誤りだからです。

単一のイベントストリームに限定したルールは、その限定を保ちます。このコアのバージョンが認識できないソース種別のルールは、黙ってすべてのストリームへ広がるのではなく、照合エンジンから除外されてログに記録されます。

監視自身が暗くなったとき

ここまでのアラートはすべて、ポーリング結果が届くことを前提にしています。だからこそ、ポーラーがいなくなることは、アラートエンジンが判断できない唯一の障害になります。ポーラープールが最後の生存ポーラーを失うと、そのジョブは誰も購読していないサブジェクトへ流れて捨てられ、ノードは down ではなく unknown に流れていきます。拠点まるごとが監視対象から外れているのに、どのダッシュボードも平穏に見えます。

Yagra はこの状態を直接監視します。ノードを抱えたまま生存ポーラーが 0 台になったプールは、それ自体が critical のアラートを上げ、他のアラートと同じ通知チャネル・ルーティングルールで配信され、ポーラーが戻れば自動的にクローズされます。

通知だけでなく、通常のアラートとして扱われます — Active alerts とアラート履歴に現れ、ライブストリームに流れ、通知テンプレートで描画されます。
既定では 5 分待ちます。 ポーラーは終了時に自ら離脱を通知するため、通常のローリング再起動でも条件は即座に成立します。この待ち時間は、そのたびに誰かを呼び出さないためのものです。 YAGRA_POOL_COVERAGE_ALERT_AFTER_SECS で調整・無効化できます（設定）。
主体はノードではなくプールです。 どの機器のものでもない唯一のアラートなので、ノードの表示状態には丸め込まれず、ミュートもできません（ミュートはノードを名指しするものです）。API クライアントは、アラートの node フィールドをノード ID として読む前に subject_kind で分岐してください。
Meraki 管理ノードは除外されます。コアの org コレクタが直接ポーリングするため、プールに依存しません。

アラートの有効・無効に関わらず、ゲージは 2 本とも出力されます — yagra_pools_without_live_poller（ラベル無し。アラートやスケールアップの起点にするのはこちら）と yagra_pool_nodes_without_live_poller{pool}。後者は健全なプールでは系列が消えるのではなく 0 を報告します。

アラートの扱い

Active alerts は、いま何が起きているかを振り分けるための画面です。現在発報中のアラートを新しい順に、重大度、ノードの名前（id はホバーで表示）、そのチェックが何を測ってどう超過したか — たとえば icmp_rtt_ms above 100 (was 450) — と経過時間とともに並べます。リストは仮想化されているため、大規模障害で数千件が同時に上がっていても滑らかなままです。トップバーの通知ベルはアクティブ件数を表示し、このビューを開きます。各ノードの詳細ページにも、そのノードに紐づく現在のアラートが表示されます。
アラートの**確認（ACK）**は、対応中であることを示すオペレーターの操作です（インシデント対応権限、Operator 以上）。確認は解除することもできます。ロールと権限はユーザーと SSOで扱います。
アラート履歴は、すべての発報と解消の追記専用の記録です。各エントリは「What」列に発報時点で 捉えたメトリクスと条件を保持するため、発報の元になったしきい値ルールがあとから編集されたり削除されたりしても、履歴は真実であり続けます。アクティブアラートと履歴は同じフォーマッタを通して測定値を描画するので、2 つの画面が食い違うことはありません。

オペレーターの操作 — 確認、ミュート、メンテナンスウィンドウの開始 — は、他のすべての状態変更操作と同じように監査ログへ記録されるので、誰が何をいつ黙らせたのかはつねに答えられます。同じ操作は Yagra の MCP ツール経由で AI や自動化クライアントからも実行でき、権限チェックも監査証跡も人が操作した場合とまったく同じです。