oodle-synthetic

Oodle 合成监控 — HTTP / TCP 检查

本技能将教 Agent 配置能真正发现故障的合成监控：设置预期状态码和延迟、合理的检查间隔，以及更新时不覆盖原有配置。

前提条件

brew install oodle-ai/oodle/oodle
oodle configure

确认合成监控端点可用：

oodle synthetic-monitors list -o json | jq 'length'

命令执行顺序

运行任何 oodle 命令前：

1. 检查上下文中是否已有目标 URL 或主机端口。
2. 如果没有，请用户确认目标。
3. 手动测试目标（curl -I <url>），确认可从公共互联网访问。
4. 运行 oodle synthetic-monitors create -f monitor.json。
5. 创建后，运行 oodle synthetic-monitors get <id> -o json，确认首次运行成功。

快速参考

任务	命令
列出监控	oodle synthetic-monitors list -o json
获取监控	oodle synthetic-monitors get <id> -o json
创建监控	oodle synthetic-monitors create -f monitor.json
更新监控	oodle synthetic-monitors update <id> -f monitor.json
删除监控	oodle synthetic-monitors delete <id> --force

常见操作

合成监控架构（HTTP）

{
  "name": "API health check",
  "enabled": true,
  "rule_type": "http",
  "rule_config": {
    "http": {
      "url": "https://api.example.com/health",
      "method": "GET",
      "expected_status_codes": [200],
      "max_response_time_ms": 2000
    }
  },
  "interval": "60s",
  "timeout": "10s",
  "conditions": {
    "critical": {"op": "<", "value": 1}
  }
}

字段	含义
rule_type	http 或 tcp（也可以是 ping、dns、ssl、traceroute、multistep）
rule_config.http	url 和 method（HTTP）
rule_config.tcp	host 和 port（TCP）
interval	探测间隔时长（如 "60s"）；最短为 10s，建议不低于 60s
timeout	超时时长；至少为 1s，且不能大于 interval
expected_status_codes	检查通过的状态码（200）或模式（"2XX"）。匹配 excluded_status_codes 中的状态码时，检查失败
max_response_time_ms	响应速度慢于此值时，检查失败
expected_body、expected_headers	响应必须包含的内容（例如 "ok"）
conditions	检查结果为 1（正常）或 0（故障），因此 {"op": "<", "value": 1} 会在检查失败时触发告警。op 是字符串：>、>=、<、<=、==、!=

合成监控架构（TCP）

{
  "name": "Postgres reachability",
  "enabled": true,
  "rule_type": "tcp",
  "rule_config": {
    "tcp": {"host": "postgres.example.com", "port": 5432}
  },
  "interval": "60s",
  "timeout": "5s",
  "conditions": {
    "critical": {"op": "<", "value": 1}
  }
}

创建监控

# ✅ CORRECT — manual reachability test, then create
curl -sSfI https://api.example.com/health
oodle synthetic-monitors create -f monitor.json

# ❌ WRONG — creating against an unreachable target leaves a permanently-failing monitor
oodle synthetic-monitors create -f monitor.json

更新监控

# ✅ CORRECT — get → edit → update preserves rule_config
oodle synthetic-monitors get syn_123 -o json > monitor.json
jq '.interval = "30s"' monitor.json > monitor.new.json
oodle synthetic-monitors update syn_123 -f monitor.new.json

# ❌ WRONG — partial payload removes rule_config
oodle synthetic-monitors update syn_123 -f <(echo '{"interval":"30s"}')

删除监控

# ✅ CORRECT
oodle synthetic-monitors get syn_123 -o json > /dev/null
oodle synthetic-monitors delete syn_123 --force

# ❌ WRONG — name-grep delete
oodle synthetic-monitors delete "$(oodle synthetic-monitors list | grep health | awk '{print $1}')" --force

最佳实践

对非关键端点使用 interval: "60s"（或更长间隔）

对每个端点都采用 10 秒间隔会增加成本和噪声。短间隔应留给面向用户的关键流程。

# ✅ CORRECT — 60s interval for a /health endpoint
"interval": "60s"

# ❌ WRONG — 10s on dozens of internal endpoints
"interval": "10s"

始终设置 expected_status_codes

如果不设置，任何 2XX 响应都会让检查通过，而这可能不是你预期的响应。

# ✅ CORRECT
"expected_status_codes": [200], "max_response_time_ms": 2000

# ❌ WRONG — monitor "succeeds" on any 2XX response
"expected_status_codes": []

添加 max_response_time_ms，以发现响应缓慢的依赖项

对于用户而言，耗时 30 秒才返回的 200 响应仍然意味着故障。

# ✅ CORRECT
"expected_status_codes": [200],
"max_response_time_ms": 2000

# ❌ WRONG — only checks status code, doesn't catch latency regressions
"expected_status_codes": [200]

更新前始终先执行 get，以保留 rule_config

更新会完整替换整个文档。

# ✅ CORRECT
oodle synthetic-monitors get syn_123 -o json > m.json
jq '.rule_config.http.expected_body = "ok"' m.json > m.new.json
oodle synthetic-monitors update syn_123 -f m.new.json

# ❌ WRONG — drops `rule_config`
oodle synthetic-monitors update syn_123 -f <(echo '{"interval":"120s"}')

每个环境使用稳定的 name

在名称中标明环境（API health check (prod)、API health check (staging)），这样告警接收者就知道该排查哪个环境。

# ✅ CORRECT
"name": "API health check (prod)"

# ❌ WRONG
"name": "health"

故障处理

错误	原因	解决方法
401 未授权	API 密钥无效或缺失	运行 oodle configure 或设置 OODLE_API_KEY
404 未找到	合成监控 ID 不存在	使用 oodle synthetic-monitors list -o json 验证
连接被拒绝	OODLE_DEPLOYMENT URL 错误	检查 OODLE_DEPLOYMENT 环境变量
监控一直显示红色	探测器的出口无法访问目标	从公共互联网运行 curl -I；检查防火墙、DNS 和 TLS 证书
监控状态反复波动	interval 过于激进，或 max_response_time_ms 设置过紧	将间隔调高至 60s；将 max_response_time_ms 调高至 p95+余量
interval must be at least 10 seconds / timeout cannot exceed interval	时长设置错误，或使用了纯数字	使用 "60s" 和 "10s" 这样的时长字符串
rule_config 被静默丢弃	使用部分载荷调用了 update	根据上一次 get 的快照重新创建；始终按 get → 编辑 → update 的顺序操作
429 请求过多	大量探测在同一秒安排执行	编辑每个监控项的 interval 以错开执行时间；批量操作时使用 --retries 3

参考资料

• Oodle CLI 仓库
• Oodle 文档