oodle-synthetic

Oodle Synthetic Monitors — HTTP / TCP チェック

このスキルでは、失敗を確実に検知する合成モニターの設定方法を説明します。期待するステータスとレイテンシ、適切な間隔、既存の設定を上書きしない更新方法を扱います。

前提条件

brew install oodle-ai/oodle/oodle
oodle configure

synthetic-monitors エンドポイントが動作することを確認します。

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

コマンド実行の順序

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

1. 対象の URL または hostport がすでにコンテキストに含まれているか確認します。
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]

rule_config を保持するため、必ず更新前に get を実行します

更新はドキュメント全体を置き換えます。

# ✅ 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 ドキュメント