oodle-alerting

Oodle 告警 — 通知器、策略、静默规则

本技能将指导 Agent 配置端到端的告警路由：通知器（告警发送到哪里）、通知策略（如何匹配和路由）以及静默规则（何时静默告警）。

先决条件

brew install oodle-ai/oodle/oodle
oodle configure

验证这三个子系统都能正常响应：

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}）会将所有生产环境告警都路由到同一个通知器。

# ✅ 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"}]

使用同一策略的严重级别进行升级，而非使用多个策略

将寻呼通知器设为 critical，将聊天频道设为同一策略中的 warn。两个同时适用于某个告警的策略会导致通知重复触发。

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

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

故障处理

错误	原因	修复方法
401 未授权	API 密钥无效或缺失	运行 oodle configure 或设置 OODLE_API_KEY
404 未找到	通知器 / 策略 / 静默规则 ID 不存在	使用对应的 list 命令进行验证
连接被拒绝	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 请求过多	批量同步策略	添加 --retries 3，将创建速率限制在每秒少于 10 次

参考资料

• Oodle CLI 仓库
• Oodle 文档