oodle-alerting

Oodle Alerting — 通知先、ポリシー、ミュート

このスキルでは、アラートのルーティングをエンドツーエンドで設定する方法を説明します。通知先（アラートの送信先）、通知ポリシー（一致条件とルーティング方法）、ミュートルール（アラートを停止するタイミング）を扱います。

前提条件

brew install oodle-ai/oodle/oodle
oodle configure

次の3つのサブシステムがすべて応答することを確認します。

oodle notifiers list -o json | jq 'length'
oodle notification-policies list -o json | jq 'length'
oodle muting-rules list -o json | jq 'length'

コマンドの実行順序

oodle コマンドを実行する前に、次の手順を行います。

1. 必要なリソース ID または名前がすでにコンテキストにあるか確認します。
2. ない場合は、検出コマンド（例：oodle notifiers list -o json）を実行します。
3. 結果が曖昧な場合は、続行する前にユーザーに確認します。
4. 解決した ID を指定して対象のコマンドを実行します。
5. 推測に基づくコマンドは実行しないでください（例：どのポリシーが参照しているか確認せずに通知先を delete しないでください）。

クイックリファレンス

タスク	コマンド
通知先の一覧表示	oodle notifiers list -o json
通知先の取得	oodle notifiers get <id> -o json
通知先の作成	oodle notifiers create -f notifier.json
通知先の更新	oodle notifiers update <id> -f notifier.json
通知先の削除	oodle notifiers delete <id> --force
ポリシーの一覧表示	oodle notification-policies list -o json
ポリシーの取得	oodle notification-policies get <id> -o json
ポリシーの作成	oodle notification-policies create -f policy.json
ポリシーの更新	oodle notification-policies update <id> -f policy.json
ポリシーの削除	oodle notification-policies delete <id> --force
ミュートルールの一覧表示	oodle muting-rules list -o json
ミュートルールの取得	oodle muting-rules get <id> -o json
ミュートルールの作成	oodle muting-rules create -f mute.json
ミュートルールの変更	update はありません。get で取得し、delete してから、編集したコピーを create します
ミュートルールの削除	oodle muting-rules delete <id> --force

よくある操作

通知先 — チャネルの定義

通知先は送信先（Slack、PagerDuty、メール、webhook）をラップします。type は数値で、設定はそのタイプに対応するフィールドに指定します。

type	送信先	設定フィールド
0	メール	email_config
1	PagerDuty	pagerduty_config
2	Slack	slack_config
3	Opsgenie	opsgenie_config
4	Webhook	webhook_config
5	Google Chat	googlechat_config
6	Microsoft Teams	msteamsv2_config
7	Rootly	rootly_config

Slack：

{
  "name": "slack-ops",
  "type": 2,
  "slack_config": { "api_url": "https://hooks.slack.com/services/T000/B000/XXXX", "channel": "#ops", "send_resolved": true }
}

PagerDuty：

{
  "name": "pd-platform",
  "type": 1,
  "pagerduty_config": { "routing_key": "abc123def456", "send_resolved": true }
}

メール：

{
  "name": "email-platform",
  "type": 0,
  "email_config": { "to": "[email protected]", "send_resolved": true }
}

Webhook：

{
  "name": "webhook-incident-bot",
  "type": 4,
  "webhook_config": { "url": "https://incidents.example.com/oodle", "send_resolved": true }
}

作成時の出力には、通知先の id（UUID）が含まれます。ポリシーとモニターは名前ではなく、この ID を使って通知先を参照します。

# ✅ CORRECT
oodle notifiers create -f notifier.json

# ❌ WRONG — missing config field, server returns 400
oodle notifiers create -f <(echo '{"name":"x","type":2}')

通知ポリシー — ルーティング

通知ポリシーには、重大度ごとに通知先（ID）を指定します。重大度は critical、warn、no_data、any のいずれかです。ラベルマッチャーはありません。

{
  "name": "platform-prod",
  "notifiers": {
    "critical": ["<pd-platform-notifier-id>", "<slack-ops-notifier-id>"],
    "warn": ["<slack-ops-notifier-id>"]
  }
}

モニターはラベルによってアラートに一致し、その notifications リストに従ってルーティングします。各エントリにはラベルの matchers と notification_policy_id（またはインラインの notifiers）があります。マッチャーが一致した最初のエントリが使用されます。マッチャーが空のエントリは最後に配置する必要があります。

"notifications": [
  {
    "matchers": [{"type": 0, "name": "team", "value": "platform"}, {"type": 0, "name": "env", "value": "prod"}],
    "notification_policy_id": "<policy-id>"
  }
]

# ✅ CORRECT
oodle notification-policies create -f policy.json

# ❌ WRONG — references a notifier id that doesn't exist
# ("critical": ["non-existent"])

ミュートルール — スケジュール設定された停止

ミュートルールは、マッチャーにラベルが一致するアラートを、startsAt から endsAt まで（RFC 3339）停止します。

必ず _oodle_monitor_id マッチャーを含めて、特定のモニターにミュートルールを限定してください。 指定しない場合、ほかのラベルがたまたま一致した無関係なアラートまで停止する可能性があります。まず oodle monitors list -o json（または oodle monitors get <id>）でモニター ID を解決します。

マッチャーの type の値は、0 = 等しい、1 = 等しくない、2 = 正規表現一致、3 = 正規表現不一致です。

{
  "name": "deploy-window-2024-01-15",
  "matchers": [
    {"type": 0, "name": "_oodle_monitor_id", "value": "01998476-6dd3-73e8-a4c0-d9137eef6bc9"},
    {"type": 0, "name": "service", "value": "api"},
    {"type": 0, "name": "env",     "value": "prod"}
  ],
  "startsAt": "2024-01-15T02:00:00Z",
  "endsAt":   "2024-01-15T06:00:00Z"
}

# ✅ CORRECT — bounded window, scoped to a specific monitor
oodle muting-rules create -f mute.json

# ❌ WRONG — endsAt before startsAt (rejected by server)
# {"startsAt": "2024-01-15T06:00:00Z", "endsAt": "2024-01-15T02:00:00Z"}

# ❌ WRONG — no _oodle_monitor_id matcher; silences every alert with these labels
# "matchers": [{"type":0,"name":"service","value":"api"},{"type":0,"name":"env","value":"prod"}]

ベストプラクティス

新しい通知先は、重大なアラートに接続する前に、重大度の低いモニターでテストする

設定を誤った Slack webhook はエラーを出さずに失敗し、アラートがどこにも届かなくなります。

# ✅ CORRECT — create notifier, attach to a test monitor with a low `warn` threshold, fire it once,
# confirm message arrives, then attach to the production policy.
oodle notifiers create -f notifier.json
oodle monitors create -f test-monitor.json   # low `warn` threshold, routed to the new notifier
# wait for fire, confirm receipt, then:
oodle notification-policies update pol_123 -f policy.json   # adds the new notifier

# ❌ WRONG — attach an untested notifier directly to the `critical` severity of a policy
oodle notifiers create -f notifier.json
oodle notification-policies create -f policy-critical.json

削除する前に必ず通知先をgetし、どのポリシーから参照されているか確認します

有効なポリシーから参照されている通知先を削除すると、アラートが通知されずに破棄されます。

# ✅ CORRECT — find references first
oodle notifiers get notif_slack_ops -o json
oodle notification-policies list -o json | jq '.[] | select([.notifiers[]?[]?] | index("notif_slack_ops")) | .id'
oodle monitors list -o json | jq '.[] | select([.notifications[]?.notifiers[]?[]?] | index("notif_slack_ops")) | .id'
# update those policies and monitors to a different notifier, then:
oodle notifiers delete notif_slack_ops --force

# ❌ WRONG — delete without checking; live policies suddenly route to a missing notifier
oodle notifiers delete notif_slack_ops --force

ミュートルールのマッチャーには必ず_oodle_monitor_idを含めます

_oodle_monitor_idのないミュートは、ラベルがたまたま一致したすべてのアラートを抑制してしまい、意図した範囲を大幅に超えることがよくあります。抑制対象のモニターを指定してください。

# ✅ CORRECT — scoped to one monitor
"matchers": [
  {"type":0,"name":"_oodle_monitor_id","value":"01998476-6dd3-73e8-a4c0-d9137eef6bc9"},
  {"type":0,"name":"service","value":"api"}
]

# ❌ WRONG — any monitor with service=api gets silenced
"matchers": [{"type":0,"name":"service","value":"api"}]

ルールを作成する前に、oodle monitors list -o json | jq '.[] | {id,name}'でモニター ID を確認してください。

ミュートルールには必ずendsAtを設定し、終了時刻のないミュートは作成しません

誰も覚えていない終了時刻のないミュートは、重大なアラートを恒久的に抑制してしまう可能性があります。

# ✅ CORRECT — bounded mute window
"startsAt": "2024-01-15T02:00:00Z", "endsAt": "2024-01-15T06:00:00Z"

# ❌ WRONG — open-ended; alerts stay silenced forever
"startsAt": "2024-01-15T02:00:00Z", "endsAt": null

モニターのnotificationsマッチャーは、チームを一意に特定できる最小限のラベルに絞ります

広すぎるマッチャー（{env: prod}のみ）を設定すると、本番環境のすべてのアラートが1つの通知先に送られます。

# ✅ CORRECT
"matchers": [{"type":0,"name":"team","value":"platform"},{"type":0,"name":"env","value":"prod"}]

# ❌ WRONG — every prod alert routes here
"matchers": [{"type":0,"name":"env","value":"prod"}]

エスカレーションには、別々のポリシーではなく、1つのポリシー内で重大度を使います

1つのポリシーのcriticalにページャーを、warnにチャットチャンネルを設定してください。両方のポリシーが同じアラートに適用されると、通知が二重に送信されます。

# ✅ CORRECT
"notifiers": {"critical": ["<pd-platform-notifier-id>"], "warn": ["<slack-ops-notifier-id>"]}

# ❌ WRONG — two policies, both apply, both fire

エラーへの対処

エラー	原因	修正方法
401 Unauthorized	API キーが無効、または設定されていません	oodle configureを実行するか、OODLE_API_KEYを設定します
404 Not Found	通知先／ポリシー／ミュートルールの ID が存在しません	対応するlistコマンドで確認します
connection refused	OODLE_DEPLOYMENTの URL が間違っています	OODLE_DEPLOYMENT環境変数を確認します
ポリシーまたはモニターが存在しない通知先を参照しています	通知先の ID が削除されたか、間違っています	oodle notifiers list -o jsonを実行し、名前ではなくid（UUID）を使用します
notification without label matchers must be the last notification	モニターのnotifications内で、すべてに適用される項目が最後にありません	マッチャーが空の項目を末尾に移動します
Slack メッセージが届きません	Webhook URL が間違っているか、Webhook が無効化されています	Slack の受信 Webhook を再発行し、通知先のslack_config.api_urlを更新してから、再度テストします
PagerDuty インシデントが作成されません	routing_keyまたはサービスが間違っています	PagerDuty でルーティングキーを確認し、通知先のpagerduty_config.routing_keyを更新します
oodle muting-rules updateを実行するとヘルプが表示されます	ミュートルールにはupdateがありません	編集したコピーをgetし、deleteしてからcreateします
ミュートが適用されませんでした	startsAtが未来に設定されているか、ラベルマッチャーがアラートに一致していません	oodle muting-rules get <id> -o jsonを実行し、マッチャーと発火中のアラートのラベルを比較します
429 Too Many Requests	ポリシーを一括同期しています	--retries 3を追加し、作成を1秒あたり10件未満に抑えます

参考資料

• Oodle CLI リポジトリ
• Oodle ドキュメント