oodle-drop-rules

Oodle 丢弃规则 — 成本控制

此技能会教 Agent 如何安全地丢弃高量指标：先估算影响，从范围较窄的规则开始，绝不悄悄删除仪表板依赖的指标。没有采样模式：规则会丢弃所有匹配的序列，丢弃的数据无法恢复。

前提条件

brew install oodle-ai/oodle/oodle
oodle configure

确认丢弃规则端点可正常工作：

oodle drop-rules list -o json | jq 'length'

命令执行顺序

运行任何 oodle 命令之前：

1. 检查目标指标前缀和匹配器是否已在上下文中。
2. 如果没有，运行 oodle metrics query --query 'count({__name__=~"<prefix>.*"})' -o json 估算影响。
3. 确认没有关键仪表板或监控器依赖受影响的序列（参见“创建规则前估算影响”）。
4. 首次尝试时，先使用范围较窄的规则（一个指标、一个非生产环境 env）；确认该环境的仪表板和监控器没有回归后，再扩大 filters 范围。
5. 运行 oodle drop-rules create -f rule.json。

快速参考

任务	命令
列出规则	oodle drop-rules list -o json
获取规则	oodle drop-rules get <id> -o json
创建规则	oodle drop-rules create -f rule.json
更新规则	oodle drop-rules update <id> -f rule.json
删除规则	oodle drop-rules delete <id> --force

常见操作

规则架构

{
  "rule_name": "drop-noisy-debug-metrics",
  "metric_name": {"type": 2, "name": "__name__", "value": "debug_.*"},
  "filters": [
    {"type": 0, "name": "level", "value": "debug"},
    {"type": 0, "name": "env",   "value": "staging"}
  ],
  "type": "series"
}

字段	含义
rule_name	必填。规则名称
metric_name	指标名称匹配器（"name": "__name__"）
filters	标签匹配器。规则触发时必须全部匹配（逻辑 AND）
type	必填。必须为 "series"

匹配器 type：0 等于，1 不等于，2 正则匹配，3 正则不匹配。

创建规则前估算影响

# ✅ CORRECT — count series that will be affected
oodle metrics query --query 'count({__name__=~"debug_.*"})' -o json

# ✅ CORRECT — confirm no dashboard panel queries the metric (list has no panels; get each dashboard)
for uid in $(oodle dashboards list -o json | jq -r '.[].uid'); do
  oodle dashboards get "$uid" -o json | grep -q 'debug_traffic_total' && echo "$uid"
done

# ✅ CORRECT — confirm no monitor depends on it
oodle monitors list -o json | jq '.[] | select(.promql_query | contains("debug_traffic_total"))'

# ❌ WRONG — create the rule first, find out from on-call later
oodle drop-rules create -f rule.json

创建范围较窄的规则（更安全的第一步）

{
  "rule_name": "drop-debug-traffic-staging",
  "metric_name": {"type": 0, "name": "__name__", "value": "debug_traffic_total"},
  "filters": [
    {"type": 0, "name": "env", "value": "staging"}
  ],
  "type": "series"
}

# ✅ CORRECT — one metric in staging; observe for a week before widening
oodle drop-rules create -f rule.json

扩大规则范围

# ✅ CORRECT — get → change filters → update
oodle drop-rules get dr_123 -o json > rule.json
jq '.filters = [{"type": 2, "name": "env", "value": "staging|dev"}]' rule.json > rule.new.json
oodle drop-rules update dr_123 -f rule.new.json

# ❌ WRONG — partial payload nulls metric_name and filters
oodle drop-rules update dr_123 -f <(echo '{"filters":[]}')

删除（重新启用摄取）

# ✅ CORRECT
oodle drop-rules get dr_123 -o json > /dev/null
oodle drop-rules delete dr_123 --force

# ❌ WRONG — speculative delete by name match
oodle drop-rules delete "$(oodle drop-rules list | grep debug | awk '{print $1}')" --force

最佳实践

创建规则前，使用 oodle metrics query --query 'count({__name__=~"<prefix>.*"})' 估算影响

匹配序列超出预期的丢弃规则可能会掩盖真实信号。

# ✅ CORRECT
oodle metrics query --query 'count({__name__=~"kube_pod_.*"})' -o json | jq -r '.data.result[0].value[1]'
# 1742 series — confirm with the team that all 1742 are safe to drop before creating a rule

# ❌ WRONG — create rule based on a guess; later discover a critical metric was matched
oodle drop-rules create -f rule.json

首次迭代时，先在非生产环境中创建范围较窄的规则

没有采样模式。先创建范围较窄的规则，可以确认该指标确实价值较低，再将其全面丢弃。

# ✅ CORRECT — week 1: drop in staging only, observe dashboards
"filters": [{"type": 0, "name": "env", "value": "staging"}]
# week 2: if no dashboards or monitors regressed, widen the filters

# ❌ WRONG — drop everywhere on first attempt; can break a dashboard nobody remembered
"filters": []

匹配器中始终同时包含 env 和 service（或精确的 metric_name）

像 {level: debug} 这样的宽泛匹配器可能会匹配恰好具有相同标签的生产指标。

# ✅ CORRECT — scoped to one env
"filters": [{"type":0,"name":"level","value":"debug"},{"type":0,"name":"env","value":"staging"}]

# ❌ WRONG — also drops debug metrics in prod
"filters": [{"type":0,"name":"level","value":"debug"}]

更新前始终先执行 get，以保留字段

更新会完整替换整个文档。

# ✅ CORRECT
oodle drop-rules get dr_123 -o json > rule.json
jq '.filters += [{"type": 0, "name": "service", "value": "api"}]' rule.json > rule.new.json
oodle drop-rules update dr_123 -f rule.new.json

# ❌ WRONG — drops metric_name and type
oodle drop-rules update dr_123 -f <(echo '{"filters":[{"type":0,"name":"service","value":"api"}]}')

使用 drop-<metric-or-domain>-<scope> 为规则命名

使用可预测的名称，便于在仪表板出问题时查找并撤销规则。

# ✅ CORRECT
"rule_name": "drop-debug-metrics-staging"
"rule_name": "drop-kube-pod-info-prod"

# ❌ WRONG
"rule_name": "rule1"

故障处理

错误	原因	解决方法
401 Unauthorized	API 密钥无效或缺失	运行 oodle configure 或设置 OODLE_API_KEY
404 Not Found	丢弃规则 ID 不存在	使用 oodle drop-rules list -o json 验证
connection refused	OODLE_DEPLOYMENT URL 错误	检查 OODLE_DEPLOYMENT 环境变量
rule_name cannot be empty	缺少 rule_name	添加 rule_name
type cannot be empty / invalid type "...", must be "series"	type 缺失或错误	设置 "type": "series"
仪表板面板突然为空	丢弃规则匹配了面板查询的指标	运行 oodle drop-rules list -o json 查找规则；删除规则（oodle drop-rules delete <id> --force）或缩小其匹配范围
监控器进入 no data 状态	丢弃规则匹配了监控器的指标	采用上述相同的解决方法
成本没有下降	匹配器实际上没有匹配高量序列	使用规则的匹配器重新运行 count(...) 查询，并比较标签集
429 Too Many Requests	批量同步丢弃规则	添加 --retries 3，将创建速率限制在每秒 <10 次

References

• Oodle CLI repo
• Oodle docs