概念
- アラート — ルールそのものです。何をチェックするか（トリガー）、どのくらいの頻度で（評価間隔）、いつ問題とみなすか（複合ロジック）、緊急度（重要度）、誰に/どこへ通知するか（チャンネル）を定義します。
- インシデント — アラートが発火したときに発生するものです。1 つのアラートに対して、同時に開いているインシデントは最大 1 つです。繰り返し違反が発生した場合は、同じインシデントのエビデンスが更新されます。インシデントはオペレーターが解決します。ルールが違反しなくなったときの自動解決は計画中ですが、現時点では有効になっていません。
- チャンネル — 通知の送信先です：メール、Slack、汎用 Webhook、またはダッシュボード内。各アラートには任意の組み合わせを設定できます。
default 組織がそれに当たります）。インシデントはトリアージのために個々のオペレーターに割り当てることができます。
トリガータイプ
それぞれ独自の JSON 仕様を持つ 5 種類があります。「問題あり」をどのように表現したいかに合ったものを選んでください。ダッシュボードの新規アラートフォームは、選択したトリガータイプに合わせて条件エディターを切り替えながら、同じ仕様を構築します。
1. metric_threshold
最もシンプルなタイプです。定義済みのリストからメトリクス、演算子、しきい値、時間ウィンドウを選択します。
演算子：
>、>=、<、<=、==（gt、gte、lt、lte、eq も使用可）。
オプションフィルター：environment、event_type。
仕様の例：
2. custom_sql
プリセットのメトリクスでカバーできないあらゆる用途に使用します。オペレーターが記述した SQL は、ディスパッチャーが実行する前に、/queries/run と同じガード（SELECT/WITH のみ、単一ステートメント、10,000 行上限）を通過します。2 つのモードがあります。
- rows モード（
op/valueなし）：クエリが少なくとも 1 行を返した時点でアラートが発火します。 - value モード：クエリは 1 つのカラムを
metric_valueとしてエイリアスする必要があり、ディスパッチャーは最初の行のmetric_valueをopを使ってvalueと比較します。
3. evaluation_score
agenteye.evaluations を読み取り、ウィンドウ内の指定されたスコアの平均値を比較します。
min_count は単一サンプルの外れ値からの保護です。ウィンドウ内に少なくとも N 件の評価が存在するまで、ディスパッチャーは発火しません。
4. eval_compound
複数の評価スコアにまたがって初めて現れる品質低下を検出します。evaluation_score が単一の名前付きスコアを監視するのに対し、eval_compound は複数の評価スコア条件を 1 つのアラートに組み合わせ、選択したロジックで結果を結合します。これにより、「ヘルプフルネスが低下またはハルシネーションが増加した場合に発火」「ヘルプフルネスかつツール効率の両方が低下した場合のみ発火」「3 つのチェックのうち少なくとも 2 つが違反した場合に発火」といったルールを 1 つで表現できます。
各条件は、共有ウィンドウにわたって agenteye.evaluations から 1 つの名前付きスコアの平均値を読み取り、独自の演算子としきい値でテストします。ブール値の結果は combinator によって結合されます。
combinator："any"、"all"、または{ "at_least": N }。conditions[]：各要素は{ score_key, op, value }で、他のトリガーと同じ演算子（>、>=、<、<=、==）を使用します。window_secs：すべての条件に適用される共通のルックバック期間（デフォルト3600）。min_count：条件が違反と判定される前に必要な評価の最小件数（条件ごと）。ウィンドウ内のサンプルが少なすぎる条件は「違反なし」としてカウントされます（デフォルト1）。environment：省略可能。すべての条件を 1 つの環境に限定します。
5. per_event
「X に一致するイベントが発生した」というアラートに使用します。集計は行わず、ディスパッチャーはルックバックウィンドウ内に一致するものを見つけた時点で発火します。
ヒント：同じイベントへの二重通知を防ぐために、
lookback_secs をアラートの eval_interval_secs とおおよそ一致させるように設定してください。
/errors からのショートカット： エラービューの各エラーグループの代表行（およびエラーイベントのセッションイベント詳細パネル）には + アラート ボタンがあります。このボタンをクリックすると、その行の event_type と環境に紐づいた per_event トリガーが事前に入力された状態で /alerts/new が開きます。ペイロードに error_type が存在する場合は、それから生成された名前も入力されます。チャンネルの選択とルックバックの確認は引き続き必要ですが、マッチャーは自動的に入力されます。このボタンを表示するにはオペレーターに alerts:write 権限が必要です。
複合ロジック（M of N）
すべてのアラートには、トリガーに加えて 2 つの整数設定があります。eval_window：参照する直近の評価数（デフォルト 1）min_breaches：アラートを発火させるために必要な違反数（デフォルト 1）
1 of 1（デフォルト）は「最初の違反で発火」を意味します。3 of 5 は「直近 5 回の評価のうち 3 回違反した場合に発火」を意味し、単一の悪い測定値がノイズになりやすい不安定なシグナルに便利です。ディスパッチャーはアラートごとにリングバッファを管理するため、状態を自分で管理する必要はありません。
評価間隔
eval_interval_secs は、ディスパッチャーがルールを実行する頻度を制御します。[30, 86400] の範囲に制限されます。ダッシュボードのプリセット：1 分 / 5 分 / 15 分 / 1 時間。基となるシグナルの変化速度に合わせた間隔を選んでください。5 分間のエラー率アラートを 15 秒ごとに評価するのは CPU の無駄遣いです。また、イベント単位のアラートはルックバックを短くしないと、評価のタイミング間でイベントが検出されずに失われる可能性があります。
チャンネル
各アラートには以下の 4 種類の任意の組み合わせを設定できます。チャンネルごとの認証情報（Slack の Webhook URL、汎用 Webhook の URL と署名シークレット、デフォルトのメール受信者）は/settings で一度設定し、各アラートからキーで参照します。これにより、1 つの Slack チャンネルを多くのアラートで共有でき、各アラートが Webhook URL のコピーを保持する必要がありません。
3 つの外部チャンネル種別（メール、Slack、Webhook）は、組織全体のキルスイッチ alerts.enabled_channels によっても制御されます。発火したアラートに設定されているチャンネル種別がこのセットに含まれていない場合、ディスパッチャーはそのチャンネルをスキップし、ステータスを skipped_disabled、ターゲットを <channel_disabled> とした alert_notifications 行を記録します（これにより、すべてのルールを編集することなく、例えば Slack への配信をグローバルに一時停止できます）。ダッシュボード内チャンネルは常に許可されています。詳細は設定を参照してください。
メール
OTP ログインメールを送信するのと同じ SMTP トランスポートを再利用します。受信者は以下の順序で解決されます。- チャンネルごとの
recipients[]オーバーライド（空でない場合）。 alerts.email_default_recipients設定（メールアドレスの配列）。
alert_notifications 行をターゲット <smtp_unconfigured> で記録するため、監査証跡で設定ミスを確認できます。
Slack
受信 Webhook URL に Block Kit メッセージを送信します。- デフォルト URL：
alerts.slack_default_webhook（/settingsで設定）。 - アラートごとのオーバーライド：チャンネルの
webhook_setting_keyを他の URL 型設定キー（例：alerts.slack_oncall、alerts.slack_costs）に設定します。
:rotating_light: / :warning: / :bell:）が含まれ、メッセージにはインシデントページへのディープリンクボタンが付いています。
汎用 Webhook
PagerDuty、Opsgenie、または独自の取り込みエンドポイントへの JSON POST インテグレーションです。ボディの形式：alerts.webhook_signing_secret が設定されている場合、リクエストにはシークレットを使ったボディの HMAC-SHA256 である X-AgentEye-Signature: sha256=<hex> ヘッダーが含まれます。ペイロードを信頼する前に、受信側で検証してください。
X-AgentEye-Event ヘッダーには alert.firing / alert.test が入ります（alert.resolved は計画中の自動解決機能用に予約されており、現時点では送信されません）。
ダッシュボード内
外部への配信はなく、アラートはダッシュボードのインシデントページに表示されるalert_notifications 行を書き込むだけです。ルールを調整中で外部システムへの通知を送りたくない場合や、通常のトリアージ中にオペレーターが確認する緊急度の低いアラートに便利です。
インシデントのライフサイクル
- firing — ディスパッチャーがインシデントを新規作成したか、別の違反を検出しました。発火通知は（インシデントの
notified_firing_atタイムスタンプによるゲート制御で）正確に 1 回だけファンアウトされます。 - acknowledged — オペレーターが
/incidents/:idで ack を押しました。インシデントはまだオープンとみなされます。その後の違反はエビデンスを更新しますが、再通知はされません。 - resolved — オペレーターが resolve を押しました。ルールの違反が止まったときの自動解決は計画中ですが、現時点では有効になっていないため、オープンなインシデントはオペレーターが解決するまでオープンのままです。
必要な権限
アラートルールの作成とインシデントのトリアージは別々の関心事であり、それぞれ個別の権限が必要です。これにより、オンコールローテーションにルールの書き換え権限を与えることなく、インシデントへのアクセス権を付与できます。alerts:read：アラートルールの表示。alerts:write：アラートルールの作成、編集、削除、テスト通知のトリガー。incidents:read：インシデントの表示。incidents:write：アラートに紐づかない手動（アドホック）インシデントのオープン。incidents:ack：インシデントの承認、割り当て、コメント、解決。
レガシーAPI キー（alerts:ack。 旧alerts:ackトークンが付与されたキーとオペレーターは引き続き機能します。incidents:ackとして受け入れられ（incidents:readも含む）、既存のオンコール担当者は資格情報を再発行することなくアクセスを維持できます。新しい権限付与にはincidents:*ファミリーを使用してください。
POST /keys）とオペレーター（PUT /users/:id）に付与します。ダッシュボードの PermGate は権限がない場合に関連ボタンをロックし、アクションの横に // 403 が表示されます。
メール受信者ピッカー。 アラートエディターの受信者ピッカーは、組織のメンバーを一覧表示し、名前で選択できます。alerts:readまたはalerts:writeを持つオペレーターであれば読み込まれます。この用途でチームのディレクトリを表示するためにusers:readは不要で、ピッカーはメンバーのメールアドレスのみを返し、完全なユーザーレコードは返しません。
設定
ディスパッチャーが使用する環境変数：
一時的な評価の失敗（ClickHouse が到達不可能、クエリのタイムアウト）が発生した後、ディスパッチャーは指数バックオフでルールを再試行します。ルールが一時的な失敗を 5 回連続で蓄積すると、バックオフを継続する代わりに通常のサイクルで再スケジュールされるため、永続的に失敗しているルールでも引き続き再評価されます。この上限は固定であり、オペレーターが調整することはできません。
チャンネル設定（環境変数ではなく
/settings から管理）：
alerts.email_default_recipients（email_list）：メールアドレスの JSON 配列。メールチャンネルのデフォルト受信者。alerts.slack_default_webhook（url）：デフォルトの Slack 受信 Webhook URL。alerts.webhook_default_url（url）：デフォルトの汎用 Webhook URL。alerts.webhook_signing_secret（secret）：HMAC-SHA256 キー。GET レスポンスでは常に""として返されます。ローテーションするには新しい値を入力してください。alerts.enabled_channels（channel_set）：アラート発火時にディスパッチされる外部チャンネル種別の組織全体のセット。デフォルトはすべての 3 種別（email、slack、webhook）。ここから種別を削除すると、各ルールを編集することなく、そのチャンネルをすべてのアラートでグローバルに抑制します。ダッシュボード内チャンネルは常に配信され、この設定の影響を受けません。
新しいアラートの検証
新しいアラートを本番利用する前に：- 少なくとも 1 つの通知チャンネルを設定して有効な状態で保存します。
- アラート詳細ページでテストを選択し、設定した各送信先がテスト通知を受信することを確認します。
- 最初の実際の違反が発生したら、インシデントページにインシデントが表示されること、および測定値が対応するダッシュボードクエリと一致することを確認します。