oodle-synthetic

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oodle Synthetic Monitors — HTTP / TCP Checks

Oodle合成监控——HTTP/TCP检查

This skill teaches the agent to configure synthetic monitors that actually catch failures: assertions, sane intervals, and update-without-overwrite.

本技能指导Agent配置能够有效捕获故障的合成监控，支持断言、合理检测间隔以及非覆盖式更新。

Prerequisites

前提条件

bash

brew install oodle-ai/oodle/oodle
oodle configure

Confirm the synthetic-monitors endpoint works:

bash

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

bash

brew install oodle-ai/oodle/oodle
oodle configure

确认synthetic-monitors端点正常工作：

bash

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

Command Execution Order

命令执行顺序

Before running any oodle command:

Check whether the target URL or hostport is already in context.
If not, ask the user to confirm the target.
Test the target manually (
```
curl -I <url>
```
) to confirm it is reachable from the public internet.

Run

oodle synthetic-monitors create -f monitor.json

After creation, verify the first run succeeded with
```
oodle synthetic-monitors get <id> -o json
```
.

在运行任何oodle命令之前：

检查目标URL或hostport是否已在上下文环境中。
如果没有，请请求用户确认目标信息。
手动测试目标（
```
curl -I <url>
```
）以确认其可从公网访问。

运行

oodle synthetic-monitors create -f monitor.json

。

创建完成后，使用
```
oodle synthetic-monitors get <id> -o json
```
验证首次运行是否成功。

Quick Reference

快速参考

Task	Command
List monitors	`oodle synthetic-monitors list -o json`
Get monitor	`oodle synthetic-monitors get <id> -o json`
Create monitor	`oodle synthetic-monitors create -f monitor.json`
Update monitor	`oodle synthetic-monitors update <id> -f monitor.json`
Delete monitor	`oodle synthetic-monitors delete <id> --force`

任务	命令
列出监控	`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`

Common Operations

常见操作

Synthetic monitor schema (HTTP)

合成监控schema（HTTP）

json

{
  "name": "API health check",
  "type": "http",
  "target": "https://api.example.com/health",
  "interval": 60,
  "assertions": [
    {"type": "statusCode",   "value": "200"},
    {"type": "responseTime", "value": "2000"}
  ]
}

Field	Meaning
`type`	`http` or `tcp`
`target`	URL (HTTP) or `host:port` (TCP)
`interval`	Seconds between probes; minimum 30, recommended ≥ 60
`assertions[].type`	`statusCode` , `responseTime` , `bodyContains` , `headerEquals`
`assertions[].value`	String form of the expected value (e.g. `"200"` , `"2000"` , `"ok"` )

json

{
  "name": "API health check",
  "type": "http",
  "target": "https://api.example.com/health",
  "interval": 60,
  "assertions": [
    {"type": "statusCode",   "value": "200"},
    {"type": "responseTime", "value": "2000"}
  ]
}

字段	含义
`type`	`http` 或 `tcp`
`target`	URL（HTTP）或 `host:port` （TCP）
`interval`	探测间隔（秒）；最小30秒，推荐≥60秒
`assertions[].type`	`statusCode` 、 `responseTime` 、 `bodyContains` 、 `headerEquals`
`assertions[].value`	预期值的字符串形式（例如 `"200"` 、 `"2000"` 、 `"ok"` ）

Synthetic monitor schema (TCP)

合成监控schema（TCP）

json

{
  "name": "Postgres reachability",
  "type": "tcp",
  "target": "postgres.example.com:5432",
  "interval": 60,
  "assertions": [
    {"type": "responseTime", "value": "1000"}
  ]
}

json

{
  "name": "Postgres reachability",
  "type": "tcp",
  "target": "postgres.example.com:5432",
  "interval": 60,
  "assertions": [
    {"type": "responseTime", "value": "1000"}
  ]
}

Creating a monitor

创建监控

bash

undefined

bash

undefined

✅ 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

undefined

oodle synthetic-monitors create -f monitor.json

undefined

Updating a monitor

更新监控

bash

undefined

bash

undefined

✅ CORRECT — get → edit → update preserves all assertions

✅ 正确操作 — 获取→编辑→更新可保留所有断言

oodle synthetic-monitors get syn_123 -o json > monitor.json jq '.interval = 30' monitor.json > monitor.new.json oodle synthetic-monitors update syn_123 -f monitor.new.json

❌ WRONG — partial payload removes assertions

❌ 错误操作 — 部分payload会删除断言

oodle synthetic-monitors update syn_123 -f <(echo '{"interval":30}')

undefined

oodle synthetic-monitors update syn_123 -f <(echo '{"interval":30}')

undefined

Deleting a monitor

删除监控

bash

undefined

bash

undefined

✅ 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

undefined

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

undefined

Best Practices

最佳实践

Use

interval: 60

(or higher) for non-critical endpoints

对非关键端点使用

interval: 60

（或更高）

A 10-second interval on every endpoint multiplies cost and noise. Reserve short intervals for critical user-facing flows.

bash

undefined

对每个端点设置10秒间隔会增加成本和告警噪音。仅为关键用户面向流程保留短间隔。

bash

undefined

✅ CORRECT — 60s interval for a /health endpoint

✅ 正确操作 — /health端点使用60秒间隔

"interval": 60

❌ WRONG — 10s on dozens of internal endpoints

❌ 错误操作 — 数十个内部端点使用10秒间隔

"interval": 10

undefined

"interval": 10

undefined

Always include at least one

statusCode

assertion

始终至少包含一个

statusCode

断言

A monitor with no assertions only checks TCP reachability — it will pass even if the app returns 500 to every request.

bash

undefined

没有断言的监控仅检查TCP可达性——即使应用对所有请求返回500，监控仍会显示正常。

bash

undefined

✅ CORRECT

✅ 正确操作

"assertions": [{"type":"statusCode","value":"200"},{"type":"responseTime","value":"2000"}]

❌ WRONG — monitor "succeeds" on a 500 response

❌ 错误操作 — 应用返回500时监控仍显示“正常”

"assertions": []

undefined

"assertions": []

undefined

Add a

responseTime

assertion to catch slow dependencies

添加

responseTime

断言以捕获缓慢依赖

A 200 response that takes 30 seconds is still a failure for users.

bash

undefined

耗时30秒的200响应对用户来说仍是故障。

bash

undefined

✅ CORRECT

✅ 正确操作

"assertions": [ {"type":"statusCode","value":"200"}, {"type":"responseTime","value":"2000"} ]

❌ WRONG — only checks status code, doesn't catch latency regressions

❌ 错误操作 — 仅检查状态码，无法捕获延迟回归

"assertions": [{"type":"statusCode","value":"200"}]

undefined

"assertions": [{"type":"statusCode","value":"200"}]

undefined

Always

get

before

update

to preserve assertions

更新前务必先

get

以保留断言

Update is a full-document replace.

bash

undefined

更新操作是全文档替换。

bash

undefined

✅ CORRECT

✅ 正确操作

oodle synthetic-monitors get syn_123 -o json > m.json jq '.assertions += [{"type":"bodyContains","value":"ok"}]' m.json > m.new.json oodle synthetic-monitors update syn_123 -f m.new.json

❌ WRONG — drops

assertions

and

target

❌ 错误操作 — 会丢失

assertions

和

target

oodle synthetic-monitors update syn_123 -f <(echo '{"interval":120}')

undefined

oodle synthetic-monitors update syn_123 -f <(echo '{"interval":120}')

undefined

Use a stable

name

per environment

为每个环境使用稳定的

name

Encode env in the name (

API health check (prod)

API health check (staging)

) so the alert recipient knows which env to investigate.

bash

undefined

在名称中编码环境信息（如

API health check (prod)

、

API health check (staging)

），以便告警接收者知晓需要排查哪个环境。

bash

undefined

✅ CORRECT

✅ 正确操作

"name": "API health check (prod)"

❌ WRONG

❌ 错误操作

"name": "health"

undefined

"name": "health"

undefined

Failure Handling

故障处理

Error	Cause	Fix
401 Unauthorized	Invalid or missing API key	Run `oodle configure` or set `OODLE_API_KEY`
404 Not Found	Synthetic monitor ID does not exist	Verify with `oodle synthetic-monitors list -o json`
connection refused	Wrong `OODLE_DEPLOYMENT` URL	Check `OODLE_DEPLOYMENT` env var
Monitor permanently red	Target unreachable from the probe egress	`curl -I` from the public internet; check firewall, DNS, TLS cert
Monitor flaps	`interval` too aggressive or `responseTime` assertion too tight	Raise interval to 60s; raise `responseTime` to p95+headroom
Assertions silently dropped	`update` was called with a partial payload	Re-create from the last `get` snapshot; always `get` → edit → `update`
429 Too Many Requests	Many probes scheduled at the same second	Stagger by editing `interval` per monitor; use `--retries 3` for bulk operations

错误	原因	修复方案
401 Unauthorized	API密钥无效或缺失	运行 `oodle configure` 或设置 `OODLE_API_KEY` 环境变量
404 Not Found	合成监控ID不存在	使用 `oodle synthetic-monitors list -o json` 验证
connection refused	`OODLE_DEPLOYMENT` URL错误	检查 `OODLE_DEPLOYMENT` 环境变量
监控持续显示异常	探测出口无法访问目标	从公网执行 `curl -I` 测试；检查防火墙、DNS、TLS证书
监控状态频繁波动	`interval` 设置过于激进或 `responseTime` 断言阈值过严	将间隔提升至60秒；将 `responseTime` 阈值设置为p95+预留值
断言被静默删除	使用部分payload调用 `update` 操作	从最近的 `get` 快照重新创建；始终遵循 `get` →编辑→ `update` 流程
429 Too Many Requests	大量探测任务被安排在同一秒执行	通过编辑每个监控的 `interval` 错开时间；批量操作时使用 `--retries 3`

oodle-synthetic

Original

Translation

Oodle Synthetic Monitors — HTTP / TCP Checks

Oodle合成监控——HTTP/TCP检查

Prerequisites

前提条件

Command Execution Order

命令执行顺序

Quick Reference

快速参考

Common Operations

常见操作

Synthetic monitor schema (HTTP)

合成监控schema（HTTP）

Synthetic monitor schema (TCP)

合成监控schema（TCP）

Creating a monitor

创建监控

✅ CORRECT — manual reachability test, then create

✅ 正确操作 — 先手动测试可达性，再创建

❌ WRONG — creating against an unreachable target leaves a permanently-failing monitor

❌ 错误操作 — 针对不可达目标创建监控会导致监控持续失败

Updating a monitor

更新监控

✅ CORRECT — get → edit → update preserves all assertions

✅ 正确操作 — 获取→编辑→更新可保留所有断言

❌ WRONG — partial payload removes assertions

❌ 错误操作 — 部分payload会删除断言

Deleting a monitor

删除监控

✅ CORRECT

✅ 正确操作

❌ WRONG — name-grep delete

❌ 错误操作 — 通过名称匹配删除

Best Practices

最佳实践

Use interval: 60 (or higher) for non-critical endpoints

对非关键端点使用interval: 60（或更高）

✅ CORRECT — 60s interval for a /health endpoint

✅ 正确操作 — /health端点使用60秒间隔

❌ WRONG — 10s on dozens of internal endpoints

❌ 错误操作 — 数十个内部端点使用10秒间隔

Always include at least one statusCode assertion

始终至少包含一个statusCode断言

✅ CORRECT

✅ 正确操作

❌ WRONG — monitor "succeeds" on a 500 response

❌ 错误操作 — 应用返回500时监控仍显示“正常”

Add a responseTime assertion to catch slow dependencies

添加responseTime断言以捕获缓慢依赖

✅ CORRECT

✅ 正确操作

❌ WRONG — only checks status code, doesn't catch latency regressions

❌ 错误操作 — 仅检查状态码，无法捕获延迟回归

Always get before update to preserve assertions

更新前务必先get以保留断言

✅ CORRECT

✅ 正确操作

❌ WRONG — drops assertions and target

❌ 错误操作 — 会丢失assertions和target

Use a stable name per environment

为每个环境使用稳定的name

✅ CORRECT

✅ 正确操作

❌ WRONG

❌ 错误操作

Failure Handling

故障处理

References

参考资料

Use
`interval: 60`
(or higher) for non-critical endpoints

对非关键端点使用
`interval: 60`
（或更高）

Always include at least one
`statusCode`
assertion

始终至少包含一个
`statusCode`
断言

Add a
`responseTime`
assertion to catch slow dependencies

添加
`responseTime`
断言以捕获缓慢依赖

Always
`get`
before
`update`
to preserve assertions

更新前务必先
`get`
以保留断言

❌ WRONG — drops
`assertions`
and
`target`

❌ 错误操作 — 会丢失
`assertions`
和
`target`

Use a stable
`name`
per environment

为每个环境使用稳定的
`name`