oodle-monitors

Oodle モニター — CRUD とアラート

このスキルでは、アラートが実用的で、対象が適切に限定され、頻繁に状態が変動しないように、エージェントが 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>

新しいモニターを作成する前に、認証が済んでいることと、少なくとも 1 回はモニター一覧の取得に成功することを確認してください。

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")'
モニターを 1 件取得	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 のうち少なくとも 1 つを指定します。
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
トレーススパン	oodle_trace_metrics	oodle-traces
GenAI スパン	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 を記載し、ラベルで振り分ける

アクションのないアラートはノイズです。すべてのモニターで、「何をすべきか」（注釈）と「誰に通知するか」（通知ポリシーが振り分けに使うラベル、または 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 のラベルを付ける

ラベルは、通知ポリシーによるアラートの振り分けや、oodle monitors list -o json の結果を jq でフィルタリングする際に使います。

# ✅ 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 の条件がありません	1 つ以上の条件を追加してください
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 アラート	エージェントがレポートしていないか、ラベルフィルターですべてのホストが除外されています	エージェントが稼働中であることを確認し（oodle metrics query --query 'up' -o json）、一致する時系列があることを確認できるまでラベルフィルターを広げてください
429 Too Many Requests	モニターの一括作成がレート制限に達しました	--retries 3 を追加し、作成速度を 1 秒あたり 10 件未満に抑えてください

参考資料

• Oodle CLI リポジトリ
• Oodle ドキュメント