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 文档