oodle-metrics-query

Oodle Metrics クエリ — PromQL のインスタントクエリと範囲クエリ

このスキルでは、Prometheus 互換のクエリ API を使用して、Oodle メトリクスに対する PromQL のインスタントクエリと範囲クエリを実行する方法を説明します。

前提条件

brew install oodle-ai/oodle/oodle
oodle configure

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

oodle metrics query --query "up" -o json | jq '.status'

コマンドの実行順序

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

1. 必要なメトリクス名がすでに分かっているか確認します。
2. 分からない場合は、oodle metrics names --start -1h --end now を実行してメトリクス名を調べます。
3. oodle metrics labels <name> --start -1h --end now を実行して、利用可能なラベルを調べます。
4. 確認済みのメトリクス名とラベルのみを使って、PromQL 式を作成します。
5. 推測でクエリを実行しないでください。必ずメトリクスとラベルの存在を先に確認します。

クイックリファレンス

タスク	コマンド
PromQL のインスタントクエリ	oodle metrics query --query "sum(up)" -o json
特定の時刻でのインスタントクエリ	oodle metrics query --query "up" --time 1700000000 -o json
PromQL の範囲クエリ	oodle metrics query-range --query "rate(http_requests_total[5m])" --start -1h --end now --step 60s -o json
部分レスポンスを使用した範囲クエリ	oodle metrics query-range --query "up" --start -1h --end now --step 60s --partial-response -o json

一般的な操作

インスタントクエリ

PromQL 式をある時点で評価します。デフォルトでは現在の値を返しますが、特定のタイムスタンプでの値も返せます。

# CORRECT — instant query with JSON output for scripting
oodle metrics query --query "sum(up)" -o json

# CORRECT — instant query at a specific time
oodle metrics query --query "up{job=\"prometheus\"}" --time 1700000000 -o json

# CORRECT — use relative time
oodle metrics query --query "up" --time -5m -o json

# WRONG — omitting --query flag
oodle metrics query -o json

範囲クエリ

PromQL 式を時間範囲にわたって評価します。必須なのは --query のみです。--start、--end、--step のデフォルト値はそれぞれ -1h、now、60s です。時間フラグには、now、相対値（-1h、-7d）、RFC 3339、またはエポックタイムスタンプを指定できます。

# CORRECT — range query over the last hour with 60-second resolution
oodle metrics query-range --query "rate(http_requests_total[5m])" --start -1h --end now --step 60s -o json

# CORRECT — range query with absolute timestamps
oodle metrics query-range --query "up" --start 1700000000 --end 1700003600 --step 60s -o json

# CORRECT — enable partial response for degraded-mode queries
oodle metrics query-range --query "up" --start -1h --end now --step 60s --partial-response -o json

ベストプラクティス

クエリの前に oodle metrics で調べる

PromQL クエリを作成する前に、メトリクス名とラベルが存在することを必ず確認してください。存在しないメトリクスをクエリすると、エラーではなく空の結果が返されます。

# CORRECT — discover first, then query
oodle metrics names --start -1h --end now -o json | jq '.[] | select(startswith("http"))'
oodle metrics labels http_requests_total --start -1h --end now
oodle metrics query --query "sum(rate(http_requests_total[5m]))" -o json

# WRONG — guessing metric names
oodle metrics query --query "sum(rate(requests_total[5m]))" -o json

範囲クエリに適切なステップを選ぶ

ステップによって、返される時系列データの解像度が決まります。ステップが小さすぎるとデータが過剰に返され、大きすぎると詳細を見落とします。

# CORRECT — 60s step for a 1-hour window (60 data points)
oodle metrics query-range --query "up" --start -1h --end now --step 60s -o json

# CORRECT — 5m step for a 24-hour window (288 data points)
oodle metrics query-range --query "up" --start -1d --end now --step 5m -o json

# WRONG — 1s step for a 24-hour window (86400 data points — too many)
oodle metrics query-range --query "up" --start -1d --end now --step 1s -o json

エラーへの対処

エラー	原因	対処方法
401 Unauthorized	API キーが無効、または設定されていません	oodle configure を実行するか、OODLE_API_KEY を設定します
400 Bad Request	PromQL 式が無効です	https://prometheus.io/docs/prometheus/latest/querying/basics/ で構文を確認します
空の結果（エラーではありません）	メトリクスが存在しないか、時間範囲内にデータがありません。インスタントクエリは --time より前の直近 5 分間のみを読み取ります	oodle metrics names を実行してメトリクスの存在を確認します。時間範囲を広げるか、データがまばらなメトリクスには query-range --start -7d を使用します
connection refused	OODLE_DEPLOYMENT の URL が間違っています	OODLE_DEPLOYMENT 環境変数を確認し、末尾にスラッシュがないことを確認します
429 Too Many Requests	レート制限に達しました	--retries 3 を追加し、間隔を空けて、クエリ頻度を下げます
required flag(s) "query" not set	必須フラグが指定されていません	PromQL 式を指定した --query フラグを追加します

参考資料

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