oodle-log-metrics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oodle Log Metrics — Rules and Cardinality

Oodle日志指标——规则与基数

This skill teaches the agent to convert log streams into metrics safely: validate the filter, narrow the

groupBy

, and avoid creating high-cardinality time series.

本技能指导Agent安全地将日志流转换为指标：验证过滤器、精简

groupBy

标签，避免创建高基数时间序列。

Prerequisites

前置条件

bash

brew install oodle-ai/oodle/oodle
oodle configure

Confirm the log-metrics endpoint works:

bash

oodle log-metrics list -o json | jq 'length'

bash

brew install oodle-ai/oodle/oodle
oodle configure

确认日志指标端点正常工作：

bash

oodle log-metrics list -o json | jq 'length'

Command Execution Order

命令执行顺序

Before running any oodle command:

Check whether the rule's filter and
```
groupBy
```
are already in context.
If not, run a sample log query (e.g.
```
oodle traces list ...
```
or the log explorer) to verify the filter actually matches logs.
Estimate cardinality:
```
groupBy
```
count × distinct values per label.
Run
```
oodle log-metrics create -f rule.json
```
only after the filter is validated.
Do not run
```
update
```
without first running
```
get
```
to capture the existing rule.

运行任何oodle命令前：

检查规则的过滤器和
```
groupBy
```
是否已在上下文之中。
如果没有，运行示例日志查询（如
```
oodle traces list ...
```
或日志探索器）验证过滤器是否确实匹配日志。
估算基数：
```
groupBy
```
标签数量 × 每个标签的不同值数量。
仅在过滤器验证通过后，运行
```
oodle log-metrics create -f rule.json
```
。
未先运行
```
get
```
获取现有规则前，不要执行
```
update
```
操作。

Quick Reference

快速参考

Task	Command
List rules	`oodle log-metrics list -o json`
Get rule	`oodle log-metrics get <id> -o json`
Create rule	`oodle log-metrics create -f rule.json`
Update rule	`oodle log-metrics update <id> -f rule.json`
Delete rule	`oodle log-metrics delete <id> --force`

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

Common Operations

常见操作

Rule schema

规则 schema

json

{
  "name": "http_errors_from_logs",
  "filter": "level=error AND service=api",
  "groupBy": ["service", "env"],
  "metricName": "oodle.log.http_errors"
}

Field meaning:

Field	Meaning
`name`	Human identifier for the rule
`filter`	Boolean expression over log fields ( `AND` / `OR` / `NOT` , `=` , `!=` , `contains` )
`groupBy`	Labels promoted from log fields onto the emitted metric
`metricName`	The Prometheus-style metric name to emit

json

{
  "name": "http_errors_from_logs",
  "filter": "level=error AND service=api",
  "groupBy": ["service", "env"],
  "metricName": "oodle.log.http_errors"
}

字段含义：

字段	含义
`name`	规则的人工识别名称
`filter`	基于日志字段的布尔表达式（支持 `AND` / `OR` / `NOT` 、 `=` 、 `!=` 、 `contains` ）
`groupBy`	从日志字段提取并附加到生成指标上的标签
`metricName`	要生成的Prometheus风格指标名称

Creating a rule

创建规则

bash

undefined

bash

undefined

✅ CORRECT — validate filter first, then create

✅ 正确做法 — 先验证过滤器，再创建

(preview with the log explorer or

oodle traces list

if traces and logs share the same backend)

—

oodle log-metrics create -f rule.json

#（如果追踪和日志共享同一后端，可通过日志探索器或

oodle traces list

预览） oodle log-metrics create -f rule.json

❌ WRONG — creating with an untested filter; the resulting metric is silently empty

❌ 错误做法 — 使用未测试的过滤器创建规则，生成的指标会静默无数据

oodle log-metrics create -f <(echo '{"name":"x","filter":"levl=eror","groupBy":[],"metricName":"x"}')

undefined

oodle log-metrics create -f <(echo '{"name":"x","filter":"levl=eror","groupBy":[],"metricName":"x"}')

undefined

Updating a rule

更新规则

bash

undefined

bash

undefined

✅ CORRECT — get → edit → update

✅ 正确做法 — 获取→编辑→更新

oodle log-metrics get lm_123 -o json > rule.json jq '.groupBy = ["service","env"]' rule.json > rule.new.json oodle log-metrics update lm_123 -f rule.new.json

❌ WRONG — partial payload removes existing fields

❌ 错误做法 — 部分请求体会删除现有字段

oodle log-metrics update lm_123 -f <(echo '{"groupBy":["service"]}')

undefined

oodle log-metrics update lm_123 -f <(echo '{"groupBy":["service"]}')

undefined

Deleting a rule

删除规则

bash

undefined

bash

undefined

✅ CORRECT — verify and delete

✅ 正确做法 — 验证后删除

oodle log-metrics get lm_123 -o json > /dev/null oodle log-metrics delete lm_123 --force

❌ WRONG — speculative delete by name match

❌ 错误做法 — 通过名称匹配推测性删除

oodle log-metrics delete "$(oodle log-metrics list | grep errors | awk '{print $1}')" --force

undefined

oodle log-metrics delete "$(oodle log-metrics list | grep errors | awk '{print $1}')" --force

undefined

Best Practices

最佳实践

Validate the

filter

against real log volume before creating the rule

创建规则前，针对真实日志量验证

filter

A typo in the filter (

levl=eror

) creates a rule that silently emits zero data points.

bash

undefined

过滤器中的拼写错误（如

levl=eror

）会创建一个静默生成零数据点的规则。

bash

undefined

✅ CORRECT — preview matching log volume in the log explorer first;

✅ 正确做法 — 先在日志探索器中预览匹配的日志量；

only then run

oodle log-metrics create

之后再运行

oodle log-metrics create

(or temporarily create a synthetic monitor that hits the matching logs and confirm count > 0)

—

❌ WRONG — create the rule, then notice the dashboard panel is empty next week

—

oodle log-metrics create -f rule.json

undefined

#（或临时创建一个命中匹配日志的合成监控，确认计数>0）

Keep

groupBy

to 2–3 low-cardinality labels

❌ 错误做法 — 创建规则，之后才发现下周仪表盘面板为空

Each label multiplies the time-series count. Avoid

request_id

user_id

trace_id

path

(with IDs).

bash

undefined

oodle log-metrics create -f rule.json

undefined

✅ CORRECT — bounded labels

将

groupBy

限制为2-3个低基数标签

"groupBy": ["service", "env"]

每个标签都会增加时间序列的数量。避免使用

request_id

、

user_id

、

trace_id

、

path

（含ID的路径）。

bash

undefined

❌ WRONG —

user_id

blows up cardinality (one series per user)

✅ 正确做法 — 有限基数的标签

"groupBy": ["service", "env", "user_id"]

undefined

"groupBy": ["service", "env"]

Always

get

before

update

to preserve fields

❌ 错误做法 —

user_id

会大幅提升基数（每个用户对应一个序列）

update

replaces the document. Sending a single field nulls everything else.

bash

undefined

"groupBy": ["service", "env", "user_id"]

undefined

✅ CORRECT

执行

update

前务必先

get

以保留字段

oodle log-metrics get lm_123 -o json > rule.json jq '.filter = "level=error AND service=api AND status=5xx"' rule.json > rule.new.json oodle log-metrics update lm_123 -f rule.new.json

update

会替换整个文档。仅发送单个字段会将其他所有字段置空。

bash

undefined

❌ WRONG — clobbers groupBy and metricName

✅ 正确做法

oodle log-metrics update lm_123 -f <(echo '{"filter":"level=error"}')

undefined

oodle log-metrics get lm_123 -o json > rule.json jq '.filter = "level=error AND service=api AND status=5xx"' rule.json > rule.new.json oodle log-metrics update lm_123 -f rule.new.json

Use a stable, namespaced

metricName

❌ 错误做法 — 会覆盖groupBy和metricName

oodle.log.<domain>.<measurement>

makes the metric easy to find in dashboards and drop rules.

bash

undefined

oodle log-metrics update lm_123 -f <(echo '{"filter":"level=error"}')

undefined

✅ CORRECT

使用稳定的命名空间式

metricName

"metricName": "oodle.log.http_errors"

oodle.log.<领域>.<度量>

格式便于在仪表盘和过滤规则中查找指标。

bash

undefined

❌ WRONG — generic name collides with other rules

✅ 正确做法

"metricName": "errors"

undefined

"metricName": "oodle.log.http_errors"

Failure Handling

❌ 错误做法 — 通用名称会与其他规则冲突

Error	Cause	Fix
401 Unauthorized	Invalid or missing API key	Run `oodle configure` or set `OODLE_API_KEY`
404 Not Found	Log-metric rule ID does not exist	Verify with `oodle log-metrics list -o json`
connection refused	Wrong `OODLE_DEPLOYMENT` URL	Check `OODLE_DEPLOYMENT` env var
`invalid filter expression`	Filter has a syntax error	Use `field=value` (no spaces around `=` ); combine with `AND` / `OR` / `NOT`
Metric exists but has no data points	Filter doesn't match any logs	Re-test the filter in the log explorer; check label names match the log schema
Cardinality alarm in the UI	`groupBy` includes a high-cardinality field	Edit the rule to drop that field; old series age out at the regular retention
429 Too Many Requests	Bulk rule creation	Add `--retries 3` , throttle to <10 creates per second

"metricName": "errors"

undefined

References

故障处理

错误	原因	解决方法
401 Unauthorized	API密钥无效或缺失	运行 `oodle configure` 或设置 `OODLE_API_KEY` 环境变量
404 Not Found	日志指标规则ID不存在	通过 `oodle log-metrics list -o json` 验证
connection refused	`OODLE_DEPLOYMENT` URL错误	检查 `OODLE_DEPLOYMENT` 环境变量
`invalid filter expression`	过滤器存在语法错误	使用 `field=value` 格式（ `=` 前后无空格）；通过 `AND` / `OR` / `NOT` 组合条件
指标存在但无数据点	过滤器未匹配任何日志	在日志探索器中重新测试过滤器；检查标签名称与日志schema是否匹配
UI中出现基数告警	`groupBy` 包含高基数字段	编辑规则移除该字段；旧序列会按常规保留周期自动过期
429 Too Many Requests	批量创建规则	添加 `--retries 3` 参数，限制每秒创建次数<10

—

参考资料

—

oodle-log-metrics

Original

Translation

Oodle Log Metrics — Rules and Cardinality

Oodle日志指标——规则与基数

Prerequisites

前置条件

Command Execution Order

命令执行顺序

Quick Reference

快速参考

Common Operations

常见操作

Rule schema

规则 schema

Creating a rule

创建规则

✅ CORRECT — validate filter first, then create

✅ 正确做法 — 先验证过滤器，再创建

(preview with the log explorer or oodle traces list if traces and logs share the same backend)

❌ WRONG — creating with an untested filter; the resulting metric is silently empty

❌ 错误做法 — 使用未测试的过滤器创建规则，生成的指标会静默无数据

Updating a rule

更新规则

✅ CORRECT — get → edit → update

✅ 正确做法 — 获取→编辑→更新

❌ WRONG — partial payload removes existing fields

❌ 错误做法 — 部分请求体会删除现有字段

Deleting a rule

删除规则

✅ CORRECT — verify and delete

✅ 正确做法 — 验证后删除

❌ WRONG — speculative delete by name match

❌ 错误做法 — 通过名称匹配推测性删除

Best Practices

最佳实践

Validate the filter against real log volume before creating the rule

创建规则前，针对真实日志量验证filter

✅ CORRECT — preview matching log volume in the log explorer first;

✅ 正确做法 — 先在日志探索器中预览匹配的日志量；

only then run oodle log-metrics create

之后再运行oodle log-metrics create

(or temporarily create a synthetic monitor that hits the matching logs and confirm count > 0)

❌ WRONG — create the rule, then notice the dashboard panel is empty next week

Keep groupBy to 2–3 low-cardinality labels

❌ 错误做法 — 创建规则，之后才发现下周仪表盘面板为空

✅ CORRECT — bounded labels

将groupBy限制为2-3个低基数标签

❌ WRONG — user_id blows up cardinality (one series per user)

✅ 正确做法 — 有限基数的标签

Always get before update to preserve fields

❌ 错误做法 — user_id会大幅提升基数（每个用户对应一个序列）

✅ CORRECT

执行update前务必先get以保留字段

❌ WRONG — clobbers groupBy and metricName

✅ 正确做法

Use a stable, namespaced metricName

❌ 错误做法 — 会覆盖groupBy和metricName

✅ CORRECT

使用稳定的命名空间式metricName

❌ WRONG — generic name collides with other rules

✅ 正确做法

Failure Handling

❌ 错误做法 — 通用名称会与其他规则冲突

References

故障处理

参考资料

(preview with the log explorer or
`oodle traces list`
if traces and logs share the same backend)

Validate the
`filter`
against real log volume before creating the rule

创建规则前，针对真实日志量验证
`filter`

only then run
`oodle log-metrics create`

之后再运行
`oodle log-metrics create`

Keep
`groupBy`
to 2–3 low-cardinality labels

将
`groupBy`
限制为2-3个低基数标签

❌ WRONG —
`user_id`
blows up cardinality (one series per user)

Always
`get`
before
`update`
to preserve fields

❌ 错误做法 —
`user_id`
会大幅提升基数（每个用户对应一个序列）

执行
`update`
前务必先
`get`
以保留字段

Use a stable, namespaced
`metricName`

使用稳定的命名空间式
`metricName`