oodle-monitors

Oodle 监控项 — CRUD 和告警

本技能将指导 Agent 创建、验证和更新 Oodle 监控项，确保告警具有可操作性、范围明确且不会频繁抖动。

前提条件

# Install + configure (see oodle-cli skill)
brew install oodle-ai/oodle/oodle
oodle configure
# or
export OODLE_API_KEY=<key>
export OODLE_INSTANCE=<instance>
export OODLE_DEPLOYMENT=<url>

创建新监控项前，请确认已完成身份验证，且至少有一次监控项列表查询成功：

oodle monitors list -o json | jq 'length'

命令执行顺序

运行任何 oodle 命令前：

1. 检查所需的资源 ID 或名称是否已在上下文中。
2. 如果没有，运行发现命令（例如，oodle monitors list -o json）。
3. 如果结果不明确，请先让用户确认再继续。
4. 使用已解析的 ID 运行目标命令。
5. 不要运行试探性命令（例如，未先对资源执行 get，不要执行 delete）。

快速参考

任务	命令
列出所有监控项	oodle monitors list -o json
正在触发的告警	oodle monitors triggers -o json
按标签筛选	oodle monitors list -o json | jq '.[] | select(.labels.env=="prod" and .labels.team=="platform")'
获取一个监控项	oodle monitors get <id> -o json
从文件创建	oodle monitors create -f monitor.json
从文件更新	oodle monitors update <id> -f monitor.json
删除（CI）	oodle monitors delete <id> --force

常见操作

列出监控项

# ✅ CORRECT — JSON output for scripting
oodle monitors list -o json

# ✅ CORRECT — list only firing alerts
oodle monitors triggers -o json

# ✅ CORRECT — narrow by labels for a specific team
oodle monitors list -o json | jq '.[] | select(.labels.env=="prod" and .labels.team=="platform")'

# ❌ WRONG — pulling everything then grepping
oodle monitors list | grep CPU

修改前读取监控项

# ✅ CORRECT — fetch full JSON, edit, then update
oodle monitors get mon_123 -o yaml > monitor.yaml
$EDITOR monitor.yaml
oodle monitors update mon_123 -f monitor.yaml

# ❌ WRONG — building update payload from memory; overwrites unrelated fields
oodle monitors update mon_123 -f <(echo '{"conditions":{"critical":{"op":2,"value":90}}}')

创建监控项

完整且有效的监控项 JSON：

{
  "name": "High CPU on web servers",
  "promql_query": "avg by (host) (rate(node_cpu_seconds_total{env=\"prod\", service=\"api\", mode!=\"idle\"}[5m])) * 100",
  "conditions": {
    "critical": {"op": 2, "value": 80, "for": "5m", "keep_firing_for": "10m"},
    "warn": {"op": 2, "value": 60, "for": "5m", "keep_firing_for": "10m"}
  },
  "labels": {"team": "platform", "env": "prod"},
  "annotations": {
    "summary": "CPU above 80% on {{ $labels.host }}",
    "runbook": "https://runbooks.example.com/cpu"
  }
}

字段	含义
name	必填。
promql_query	必填。不含阈值的 PromQL 表达式。
conditions	必填。至少包含 critical、warn、no_data 之一。
conditions.<severity>.op	比较运算符：0 ==、1 !=、2 >、3 >=、4 <、5 <=。
conditions.<severity>.value	阈值数字。
conditions.<severity>.for	可选。条件必须持续为真的时长，超过此时长才会触发告警。
conditions.<severity>.keep_firing_for	可选。条件恢复后，告警继续触发的时长。
conditions.no_data	查询未返回数据时触发。必须为 {"op": 0, "value": 1}。
labels	监控项所有告警的标签。通知策略会根据这些标签进行路由。
annotations	告警文本。支持 {{ $labels.host }} 和 {{ $value }} 等模板。
notifications	可选，路由到通知器（参见 oodle-alerting 技能）。

# ✅ CORRECT
oodle monitors create -f monitor.json

# ❌ WRONG — no `conditions`, monitor will be rejected
oodle monitors create -f <(echo '{"name":"x","promql_query":"up"}')

更新监控项

# ✅ CORRECT — get → edit → update
oodle monitors get mon_123 -o json > monitor.json
jq '.conditions.critical.value = 85' monitor.json > monitor.new.json
oodle monitors update mon_123 -f monitor.new.json

# ❌ WRONG — sending only the changed field; missing fields become null
oodle monitors update mon_123 -f <(echo '{"conditions":{"critical":{"op":2,"value":85}}}')

删除监控项

# ✅ CORRECT — verify first, then delete
oodle monitors get mon_123 -o json > /dev/null
oodle monitors delete mon_123 --force

# ❌ WRONG — speculative delete by name match
oodle monitors delete "$(oodle monitors list | grep CPU | head -1 | awk '{print $1}')" --force

对日志和追踪数据设置告警

监控项只运行 PromQL，无法运行日志查询或 TraceQL 查询。请针对日志和追踪数据生成的指标设置告警：

来源	指标	技能
日志行（纯文本或 JSON）	oodle_logs_<name>，由日志指标规则生成，用于统计行数或使用正则表达式提取值	oodle-log-metrics
追踪 Span	oodle_trace_metrics	oodle-traces
GenAI Span	oodle_genai_*	oodle-traces

{
  "name": "Credit exhausted",
  "promql_query": "sum by (user) (increase(oodle_logs_credit_exhausted[10m]))",
  "conditions": {"critical": {"op": 2, "value": 0}},
  "labels": {"team": "billing", "env": "prod"},
  "annotations": {"summary": "User {{ $labels.user }} ran out of credit"}
}

每个超出阈值的时间序列都会触发一次告警。请在 by (...) 中保留所需的标签，以便告警名称标识用户。

最佳实践

使用 [5m]（或更长）的范围和 for，不要使用 [1m]

较短的窗口会导致告警因正常的流量峰值而频繁抖动。生产告警至少使用 [5m] 和 "for": "5m"；对于噪声较大的指标，使用 [15m]。

# ✅ CORRECT
"promql_query": "avg by (host) (rate(node_cpu_seconds_total{env=\"prod\", mode!=\"idle\"}[5m])) * 100"

# ❌ WRONG — flaps on every brief spike
"promql_query": "avg by (host) (rate(node_cpu_seconds_total{env=\"prod\", mode!=\"idle\"}[1m])) * 100"

使用明确的标签限定查询范围 — 切勿留空选择器

不含标签匹配器的选择器会匹配该指标的所有时间序列，并为不属于你的资源产生告警。

# ✅ CORRECT — scoped to a specific env + service
"promql_query": "avg by (host) (rate(node_cpu_seconds_total{env=\"prod\", service=\"api\", mode!=\"idle\"}[5m])) * 100"

# ❌ WRONG — alerts on every host in the org
"promql_query": "avg by (host) (rate(node_cpu_seconds_total[5m])) * 100"

始终为条件设置 keep_firing_for

没有恢复阈值。未设置 keep_firing_for 时，值一旦低于阈值，告警就会立即解除；轻微波动会导致告警反复解除并触发。

# ✅ CORRECT — the alert stays open 10 minutes after the value recovers
"conditions": {"critical": {"op": 2, "value": 80, "keep_firing_for": "10m"}, "warn": {"op": 2, "value": 60, "keep_firing_for": "10m"}}

# ❌ WRONG — no keep_firing_for; the monitor flaps around the threshold
"conditions": {"critical": {"op": 2, "value": 80}, "warn": {"op": 2, "value": 60}}

在 annotations 中填写操作手册 URL，并通过标签进行路由

没有操作指引的告警只是噪声。每个监控项都必须回答“我该怎么做？”（即 annotations）和“谁会收到通知？”（即通知策略用于路由的标签，或 notifications；请参阅 oodle-alerting 技能）。

# ✅ CORRECT
"annotations": {"summary": "CPU above 80% on {{ $labels.host }} (env=prod, service=api)", "runbook": "https://runbooks.example.com/cpu"}

# ❌ WRONG — no actionable content
"annotations": {"summary": "CPU is high"}

为每个监控项至少添加 team 和 env 标签

通知策略通过标签路由告警，你也可以使用标签通过 jq 过滤 oodle monitors list -o json 的结果。

# ✅ CORRECT
"labels": {"team": "platform", "env": "prod", "service": "api"}

# ❌ WRONG
"labels": {}

故障处理

错误	原因	修复方法
401 Unauthorized	API 密钥无效或缺失	运行 oodle configure 或设置 OODLE_API_KEY
404 Not Found	监控项 ID 不存在	使用 oodle monitors list -o json 验证
connection refused	OODLE_DEPLOYMENT URL 错误	检查 OODLE_DEPLOYMENT 环境变量
invalid promql query	PromQL 查询存在语法错误	使用 oodle metrics query --query '<promql>' 测试查询
missing conditions	缺少 critical、warn 或 no_data 条件	至少添加一个条件
no data condition must have op:== and value:1	no_data 格式错误	使用 "no_data": {"op": 0, "value": 1}
告警从未触发	查询没有返回数据，或阈值无法达到	运行 oodle metrics names -o json | jq -r '.[] | select(startswith("<metric>"))' 确认指标存在；暂时降低阈值并重新检查
告警过多（抖动）	范围太短，未设置 for 或 keep_firing_for	将范围增加到 [5m] 或 [15m]；设置 for 和 keep_firing_for
no data 告警	Agent 未上报，或标签筛选器排除了所有主机	验证 Agent 是否正常运行（oodle metrics query --query 'up' -o json）；扩大标签筛选范围，确认是否有任何时间序列匹配
429 Too Many Requests	批量创建监控项触发了速率限制	添加 --retries 3，将创建速率限制在每秒少于 10 个

参考资料

• Oodle CLI 仓库
• Oodle 文档