oodle-metrics

Oodle Metrics — 検索とクエリ

このスキルでは、メトリクス名を見つけ、ラベルを列挙し、最初の試行でデータを返す PromQL クエリを作成する方法をエージェントに教えます。

前提条件

brew install oodle-ai/oodle/oodle
oodle configure

メトリクスエンドポイントが動作することを確認します。

oodle metrics names -o json | jq 'length'

コマンドの実行順序

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

1. 必要なメトリクス名がすでにコンテキストにあるか確認します。
2. ない場合は、oodle metrics names -o json | jq -r '.[] | select(startswith("<prefix>"))' を実行して見つけます。
3. oodle metrics labels <name> を実行してラベルを列挙します。
4. oodle metrics label-values <name> <label> を実行して、フィルターに必要な値を列挙します。
5. 手順 3 で確認したラベルと、手順 4 で確認した値だけを使って PromQL クエリを作成します。

クイックリファレンス

タスク	コマンド
メトリクス名を一覧表示（フィルターあり）	oodle metrics names -o json | jq -r '.[] | select(startswith("<prefix>"))'
メトリクス名を一覧表示（長い期間）	oodle metrics names --start -24h --end now -o json
メトリクスのラベルを一覧表示	oodle metrics labels <name>
ラベルの値を一覧表示	oodle metrics label-values <name> <label>

names、labels、label-values は、時間範囲内にサンプルがある系列のみを読み取ります。デフォルトの範囲は直近 1 時間です。まれなイベントのメトリクス（ログメトリクス、エラーカウンターなど）はデータが疎なことが多いため、メトリクス、ラベル、値が存在しないと判断する前に、範囲を広げてください（例：--start -7d）。

よくある操作

3 ステップのラベル検索ワークフロー

初めて使うメトリクスの PromQL 式を書く前に、必ず次の 3 つのコマンドを順番に実行します。

# Step 1 — find the metric name
oodle metrics names -o json | jq -r '.[] | select(startswith("http_requests"))'
# returns e.g. ["http_requests_total", "http_requests_in_flight"]

# Step 2 — list available labels
oodle metrics labels http_requests_total
# returns e.g. ["service", "method", "status", "env"]

# Step 3 — list values for a label
oodle metrics label-values http_requests_total service
# returns e.g. ["api", "checkout", "auth"]

# ✅ CORRECT — query built from confirmed labels and values
sum by (service) (rate(http_requests_total{service="api",env="prod",status=~"5.."}[5m]))

# ❌ WRONG — guessing label names; query returns no data
sum by (svc) (rate(http_requests{app="api",environment="production",http_status=~"5.."}[5m]))

メトリクス一覧のフィルタリング

# ✅ CORRECT — narrow by prefix with jq
oodle metrics names -o json | jq -r '.[] | select(startswith("http_requests"))'

# ✅ CORRECT — widen the time range when sweeping a namespace
oodle metrics names --start -24h --end now -o json | jq -r '.[] | select(startswith("kube_"))'

# ❌ WRONG — printing every metric in the system
oodle metrics names -o json

カーディナリティを考慮したクエリ

ラベルでグループ化する前に、カーディナリティが制限されていることを確認します。

# ✅ CORRECT — confirm `service` has <100 values before grouping by it
oodle metrics label-values http_requests_total service | wc -l

# ❌ WRONG — grouping by a high-cardinality label like `request_id` melts the query
sum by (request_id) (rate(http_requests_total[5m]))

ベストプラクティス

メトリクスの一覧表示では、必ずプレフィックスでフィルターする

メトリクスの名前空間は大きく、フィルターなしの oodle metrics names は不要な出力が多くなります。

# ✅ CORRECT
oodle metrics names -o json | jq -r '.[] | select(startswith("http_requests"))'

# ❌ WRONG — returns thousands of results
oodle metrics names -o json

PromQL を書く前に、必ず 3 ステップの検索ワークフローを実行する

推測したラベル名を使うと、クエリがデータを返さず、メトリクスが見つからないように見えます。

# ✅ CORRECT — labels confirmed by step 2, values confirmed by step 3
oodle metrics labels http_requests_total
oodle metrics label-values http_requests_total service
sum by (service) (rate(http_requests_total{service="api"}[5m]))

# ❌ WRONG — writing the query first, then debugging "why is it empty?"
sum by (service_name) (rate(http_request_count{service_name="api"}[5m]))

スクリプトでは、テーブル出力を解析せず、必ず jq にパイプする

テーブル出力の列の順序と幅は一定ではありません。

# ✅ CORRECT
oodle metrics names -o json | jq -r '.[] | select(startswith("http_"))'

# ❌ WRONG
oodle metrics names | tail -n +2 | awk '{print $1}'

すべてのカウンターのレートには、rate(...[1m]) ではなく rate(...[5m]) を使う

[1m] のレートは、ボリュームの小さい系列ではノイズが多く、スクレイプの間隔が空いた場合も平滑化されません。

# ✅ CORRECT
sum by (service) (rate(http_requests_total[5m]))

# ❌ WRONG — flapping graphs, false alerts when a single scrape is missed
sum by (service) (rate(http_requests_total[1m]))

エラーへの対処

エラー	原因	対処方法
401 Unauthorized	API キーが無効、または設定されていません	oodle configure を実行するか、OODLE_API_KEY を設定します
No labels for this metric または空のリスト	メトリクス名が存在しないか、時間範囲内にサンプルがありません	oodle metrics names を実行して正しい名前を見つけ、--start -7d を指定して再試行します
接続拒否	OODLE_DEPLOYMENT の URL が間違っています	OODLE_DEPLOYMENT 環境変数を確認します
クエリ結果が空	ラベル名またはラベル値が間違っています	手順 2（labels）と手順 3（label-values）を再実行し、セレクターを修正します
クエリのタイムアウト	カーディナリティが高すぎます（例：by (request_id)）	by (...) からカーディナリティの高いラベルを除き、時間範囲を狭めます
parse error	PromQL の構文が正しくありません	まず UI のメトリクスエクスプローラーで式を検証します
429 Too Many Requests	label-values の同時呼び出しが多すぎます	--retries 3 を追加し、スクリプトで label-values の出力をキャッシュします

参考資料

• Oodle CLI リポジトリ
• Oodle ドキュメント
• PromQL リファレンス