Back to Details

oodle-metrics-query

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Oodle Metrics Query — PromQL Instant and Range Queries

Oodle指标查询 — PromQL即时查询与范围查询

This skill teaches the agent to execute PromQL instant and range queries against Oodle metrics using the Prometheus-compatible query API.
本技能指导Agent使用兼容Prometheus的查询API对Oodle指标执行PromQL即时查询和范围查询。

Prerequisites

前提条件

bash
brew install oodle-ai/oodle/oodle
oodle configure
Confirm the query endpoint works:
bash
oodle metrics query --query "up" -o json | jq '.status'
bash
brew install oodle-ai/oodle/oodle
oodle configure
确认查询端点可用：
bash
oodle metrics query --query "up" -o json | jq '.status'

Command Execution Order

命令执行顺序

Before running any query command:
  1. Check whether the required metric name is already known.
  2. If not, run 
    oodle metrics names --start -1h --end now
    to discover metric names.
  3. Run 
    oodle metrics labels <name> --start -1h --end now
    to discover available labels.
  4. Build the PromQL expression using only confirmed metric names and labels.
  5. Do not run speculative queries — always confirm metric and label existence first.
运行任何查询命令之前：
  1. 检查是否已知晓所需的指标名称。
  2. 如果未知，运行 
    oodle metrics names --start -1h --end now
    来发现指标名称。
  3. 运行 
    oodle metrics labels <name> --start -1h --end now
    来发现可用标签。
  4. 仅使用已确认的指标名称和标签构建PromQL表达式。
  5. 不要运行推测性查询——始终先确认指标和标签是否存在。

Quick Reference

快速参考

TaskCommand
Instant PromQL query
oodle metrics query --query "sum(up)" -o json
Instant query at specific time
oodle metrics query --query "up" --time 1700000000 -o json
Range PromQL query
oodle metrics query-range --query "rate(http_requests_total[5m])" --start -1h --end now --step 60s -o json
Range query with partial response
oodle metrics query-range --query "up" --start -1h --end now --step 60s --partial-response -o json
任务命令
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

Common Operations

常见操作

Instant query

即时查询

Evaluate a PromQL expression at a single point in time. Returns the current value by default, or the value at a specific timestamp.
bash
undefined
在单个时间点计算PromQL表达式。默认返回当前值，或指定时间戳的值。
bash
undefined

CORRECT — instant query with JSON output for scripting

正确示例 — 适合脚本的JSON格式输出即时查询

oodle metrics query --query "sum(up)" -o json
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
oodle metrics query --query "up{job="prometheus"}" --time 1700000000 -o json

CORRECT — use relative time

正确示例 — 使用相对时间

oodle metrics query --query "up" --time -5m -o json
oodle metrics query --query "up" --time -5m -o json

WRONG — omitting --query flag

错误示例 — 省略--query参数

oodle metrics query -o json
undefined
oodle metrics query -o json
undefined

Range query

范围查询

Evaluate a PromQL expression over a time range. All four flags (
--query
, 
--start
, 
--end
, 
--step
) are required.
bash
undefined
在时间范围内计算PromQL表达式。四个参数（
--query
、
--start
、
--end
、
--step
）均为必填项。
bash
undefined

CORRECT — range query over the last hour with 60-second resolution

正确示例 — 过去1小时内的范围查询，分辨率为60秒

oodle metrics query-range --query "rate(http_requests_total[5m])" --start -1h --end now --step 60s -o json
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
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 query-range --query "up" --start -1h --end now --step 60s --partial-response -o json

WRONG — missing --step flag

错误示例 — 缺少--step参数

oodle metrics query-range --query "up" --start -1h --end now -o json
oodle metrics query-range --query "up" --start -1h --end now -o json

WRONG — missing --start or --end

错误示例 — 缺少--start或--end参数

oodle metrics query-range --query "up" --step 60s -o json
undefined
oodle metrics query-range --query "up" --step 60s -o json
undefined

Best Practices

最佳实践

Use 
oodle metrics
to discover before querying

查询前使用
oodle metrics
进行发现

Always confirm metric names and labels exist before building a PromQL query. Querying a nonexistent metric returns empty results, not an error.
bash
undefined
构建PromQL查询之前，务必确认指标名称和标签是否存在。查询不存在的指标会返回空结果，而非错误。
bash
undefined

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
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
undefined
oodle metrics query --query "sum(rate(requests_total[5m]))" -o json
undefined

Choose the right step for range queries

为范围查询选择合适的step值

The step determines the resolution of the returned time series. Too small a step returns excessive data; too large a step misses detail.
bash
undefined
step值决定返回时间序列的分辨率。step过小会返回过多数据；step过大则会丢失细节。
bash
undefined

CORRECT — 60s step for a 1-hour window (60 data points)

正确示例 — 1小时窗口使用60秒step（60个数据点）

oodle metrics query-range --query "up" --start -1h --end now --step 60s -o json
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)

正确示例 — 24小时窗口使用5分钟step（288个数据点）

oodle metrics query-range --query "up" --start -1d --end now --step 5m -o json
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)

错误示例 — 24小时窗口使用1秒step（86400个数据点——数量过多）

oodle metrics query-range --query "up" --start -1d --end now --step 1s -o json
undefined
oodle metrics query-range --query "up" --start -1d --end now --step 1s -o json
undefined

Failure Handling

故障处理

ErrorCauseFix
401 UnauthorizedInvalid or missing API keyRun 
oodle configure
or set 
OODLE_API_KEY
400 Bad RequestInvalid PromQL expressionCheck syntax at https://prometheus.io/docs/prometheus/latest/querying/basics/
Empty result (not an error)Metric does not exist or no data in time rangeRun 
oodle metrics names
to verify the metric exists; widen the time range
connection refusedWrong 
OODLE_DEPLOYMENT
URL		Check 
OODLE_DEPLOYMENT
env var, ensure no trailing slash
429 Too Many RequestsRate limitedAdd 
--retries 3
, back off, reduce query frequency
required flag "step"
Missing required flag for range queryAdd 
--step
flag (e.g. 
--step 60s
)
required flag "query"
Missing required flagAdd 
--query
flag with a PromQL expression
错误原因解决方法
401 UnauthorizedAPI密钥无效或缺失运行
oodle configure
或设置
OODLE_API_KEY
环境变量
400 Bad RequestPromQL表达式无效访问https://prometheus.io/docs/prometheus/latest/querying/basics/检查语法
空结果（非错误）指标不存在或时间范围内无数据运行
oodle metrics names
验证指标是否存在；扩大时间范围
connection refused
OODLE_DEPLOYMENT
URL错误		检查
OODLE_DEPLOYMENT
环境变量，确保无末尾斜杠
429 Too Many Requests触发速率限制添加
--retries 3
参数，等待一段时间后重试，降低查询频率
required flag "step"
范围查询缺少必填参数添加
--step
参数（例如
--step 60s
）
required flag "query"
缺少必填参数添加
--query
参数并传入PromQL表达式

References

参考资料