oodle-metrics

Oodle 指标 — 发现与查询

此技能将教会 Agent 查找指标名称、枚举其标签，并构建能够一次就返回数据的 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 只会读取时间范围内有样本的序列。默认范围为最近一小时。罕见事件的指标（日志指标、错误计数器）通常比较稀疏，因此在判定某个指标、标签或值不存在之前，请扩大时间范围（例如 --start -7d）。

常见操作

3 步标签发现工作流

为尚未使用过的指标编写 PromQL 表达式之前，务必按顺序运行以下三个命令。

# 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(...[5m])，而非 rate(...[1m])

低流量序列使用 [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 重试
connection refused	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 参考