oodle-traces

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oodle Traces — Search and Analysis

Oodle追踪数据 — 搜索与分析

This skill teaches the agent to search Oodle traces with the right service / time / duration filters and to fetch full trace detail by ID.

本技能指导Agent使用正确的服务/时间/时长过滤器搜索Oodle追踪数据，并通过ID获取完整的追踪详情。

Prerequisites

前置条件

bash

brew install oodle-ai/oodle/oodle
oodle configure

Confirm the traces endpoint works (use a recent time window):

bash

oodle traces list --from -15m --to now -o json | jq 'length'

bash

brew install oodle-ai/oodle/oodle
oodle configure

确认追踪数据端点可用（使用最近的时间窗口）：

bash

oodle traces list --from -15m --to now -o json | jq 'length'

Command Execution Order

命令执行顺序

Before running any oodle command:

Check whether a service name and approximate time window are already in context.

If not, run

oodle traces list --from -1h --to now -o json | jq -r '.[].service' | sort -u

to discover services that emitted traces recently.

Build the search with

--service

--from

--to

and at least one of

--error

--min-duration

--operation

To inspect a single trace, run
```
oodle traces get <trace-id> -o json
```
.
Do not run
```
oodle traces list
```
without a
```
--service
```
filter on production environments.

运行任何oodle命令前：

检查上下文是否已包含服务名称和大致时间窗口。

如果没有，运行

oodle traces list --from -1h --to now -o json | jq -r '.[].service' | sort -u

来发现最近生成追踪数据的服务。

使用
```
--service
```
、
```
--from
```
、
```
--to
```
以及至少一个
```
--error
```
/
```
--min-duration
```
/
```
--operation
```
参数构建搜索命令。
要查看单个追踪数据详情，运行
```
oodle traces get <trace-id> -o json
```
。
在生产环境中，不要在未添加
```
--service
```
过滤器的情况下运行
```
oodle traces list
```
。

Quick Reference

快速参考

Task	Command
List traces in a service	`oodle traces list --service <svc> --from -1h --to now -o json`
List error traces only	`oodle traces list --service <svc> --error --from -1h -o json`
List slow traces (>500ms)	`oodle traces list --service <svc> --min-duration 500 --from -1h -o json`
Filter by operation	`oodle traces list --service <svc> --operation GET_/users --from -1h -o json`
Get full trace	`oodle traces get <trace-id> -o json`

任务	命令
列出某服务的追踪数据	`oodle traces list --service <svc> --from -1h --to now -o json`
仅列出错误追踪数据	`oodle traces list --service <svc> --error --from -1h -o json`
列出慢追踪数据（>500ms）	`oodle traces list --service <svc> --min-duration 500 --from -1h -o json`
按操作过滤	`oodle traces list --service <svc> --operation GET_/users --from -1h -o json`
获取完整追踪数据	`oodle traces get <trace-id> -o json`

Common Operations

常见操作

Searching for errors in the last hour

搜索过去一小时内的错误追踪数据

bash

undefined

bash

undefined

✅ CORRECT — scoped to one service, narrow time window, error filter on

✅ 正确 — 限定单个服务、窄时间窗口、启用错误过滤器

oodle traces list --service api --error --from -1h --to now -o json

❌ WRONG — no service, no error filter, huge result set

❌ 错误 — 未指定服务、无错误过滤器、结果集过大

oodle traces list --from -1h --to now -o json

undefined

oodle traces list --from -1h --to now -o json

undefined

Searching for slow traces

搜索慢追踪数据

bash

undefined

bash

undefined

✅ CORRECT — slow checkout traces in the last hour

✅ 正确 — 过去一小时内的慢结账追踪数据

oodle traces list --service checkout --min-duration 500 --from -1h --to now -o json

✅ CORRECT — narrow further by operation when you know the endpoint

✅ 正确 — 已知端点时进一步按操作缩小范围

oodle traces list --service checkout --operation POST_/cart --min-duration 500 --from -1h -o json

oodle traces list --service checkout --operation POST_/cart --min-duration 500 --from -1h --to now -o json

❌ WRONG — listing everything and sorting client-side wastes the API budget

❌ 错误 — 列出所有数据后在客户端排序会浪费API配额

oodle traces list --service checkout --from -1h -o json | jq 'sort_by(.durationMs) | reverse | .[0:10]'

undefined

oodle traces list --service checkout --from -1h -o json | jq 'sort_by(.durationMs) | reverse | .[0:10]'

undefined

Fetching a full trace

获取完整追踪数据

bash

undefined

bash

undefined

✅ CORRECT — list to discover trace ids, then get the one of interest

✅ 正确 — 先列出追踪数据发现trace id，再获取目标详情

TRACE_ID=$(oodle traces list --service api --error --from -15m -o json | jq -r '.[0].traceId') oodle traces get "$TRACE_ID" -o json

❌ WRONG —

oodle traces get

without an id (it expects the id as a positional arg)

❌ 错误 —

oodle traces get

需要传入id（它将id作为位置参数）

oodle traces get

undefined

oodle traces get

undefined

Time window flags

时间窗口参数

--from

and

--to

accept the same formats as the rest of the CLI:

Format	Example
Epoch seconds	`1731628800`
`now`	`now`
Relative duration	`-1h` , `-30m` , `-7d`

bash

undefined

--from

和

--to

支持与CLI其他部分相同的格式：

格式	示例
纪元秒	`1731628800`
`now`	`now`
相对时长	`-1h` , `-30m` , `-7d`

bash

undefined

✅ CORRECT

✅ 正确

oodle traces list --service api --from -30m --to now -o json

❌ WRONG — human strings are not parsed

❌ 错误 — 不解析自然语言字符串

oodle traces list --service api --from "30 minutes ago"

undefined

oodle traces list --service api --from "30 minutes ago"

undefined

Best Practices

最佳实践

Always specify

--service

to scope the search

始终指定

--service

来限定搜索范围

Trace volume can be massive; an unfiltered list is expensive and rate-limited.

bash

undefined

追踪数据量可能非常庞大；未过滤的列表会消耗大量资源并触发速率限制。

bash

undefined

✅ CORRECT

✅ 正确

oodle traces list --service api --from -1h -o json

❌ WRONG — full-tenant scan

❌ 错误 — 全租户扫描

oodle traces list --from -1h -o json

undefined

oodle traces list --from -1h -o json

undefined

Use

--error

to find failing traces, not client-side filtering

使用

--error

查找失败的追踪数据，而非客户端过滤

--error

pushes the predicate to the server and returns matches faster.

bash

undefined

--error

将筛选条件推送到服务器，返回匹配结果的速度更快。

bash

undefined

✅ CORRECT

✅ 正确

oodle traces list --service api --error --from -1h -o json

❌ WRONG — fetches every trace then filters client-side

❌ 错误 — 获取所有追踪数据后在客户端过滤

oodle traces list --service api --from -1h -o json | jq '.[] | select(.status=="error")'

undefined

oodle traces list --service api --from -1h -o json | jq '.[] | select(.status=="error")'

undefined

Use

--min-duration

to find slow traces, not client-side sort

使用

--min-duration

查找慢追踪数据，而非客户端排序

bash

undefined

bash

undefined

✅ CORRECT — server-side filter, returns ~the right number of rows

✅ 正确 — 服务器端过滤，返回数量合适的结果

oodle traces list --service api --min-duration 500 --from -1h -o json

❌ WRONG — pulls everything, sorts on the client

❌ 错误 — 获取所有数据后在客户端排序

oodle traces list --service api --from -1h -o json | jq 'sort_by(.durationMs) | reverse'

undefined

oodle traces list --service api --from -1h -o json | jq 'sort_by(.durationMs) | reverse'

undefined

Keep time windows ≤ 24h for

list

; widen by re-querying, not by raising

--to

list

命令的时间窗口保持≤24小时；如需扩大范围请重新查询，而非增大

--to

的范围

A 7-day list returns too many rows and risks timeouts. Page by hour.

bash

undefined

7天的列表会返回过多数据，可能导致超时。按小时分页查询。

bash

undefined

✅ CORRECT — bounded window

✅ 正确 — 限定窗口

oodle traces list --service api --error --from -1h --to now -o json

❌ WRONG — multi-day list

❌ 错误 — 多天范围的列表

oodle traces list --service api --error --from -7d --to now -o json

undefined

oodle traces list --service api --error --from -7d --to now -o json

undefined

Failure Handling

故障处理

Error	Cause	Fix
401 Unauthorized	Invalid or missing API key	Run `oodle configure` or set `OODLE_API_KEY`
404 Not Found	Trace ID does not exist or has aged out of retention	Re-list with a recent `--from` to find a current trace id
connection refused	Wrong `OODLE_DEPLOYMENT` URL	Check `OODLE_DEPLOYMENT` env var
Empty result	Wrong service name or time window outside retention	List recent services: `oodle traces list --from -1h -o json
Request times out	Time window too large or no service filter	Narrow `--from` / `--to` , add `--service` , add `--min-duration` or `--error`
429 Too Many Requests	Concurrent trace fetches	Add `--retries 3` ; throttle to <5 requests / second

错误	原因	修复方案
401 Unauthorized	API密钥无效或缺失	运行 `oodle configure` 或设置 `OODLE_API_KEY` 环境变量
404 Not Found	Trace ID不存在或已超出保留期限	使用最近的 `--from` 参数重新列出追踪数据，找到有效的trace id
connection refused	`OODLE_DEPLOYMENT` URL错误	检查 `OODLE_DEPLOYMENT` 环境变量
空结果	服务名称错误或时间窗口超出保留期限	列出最近的服务：`oodle traces list --from -1h -o json
请求超时	时间窗口过大或未设置服务过滤器	缩小 `--from` / `--to` 范围，添加 `--service` ，添加 `--min-duration` 或 `--error` 参数
429 Too Many Requests	并发追踪数据请求过多	添加 `--retries 3` 参数；将请求速率限制在<5次/秒

oodle-traces

Original

Translation

Oodle Traces — Search and Analysis

Oodle追踪数据 — 搜索与分析

Prerequisites

前置条件

Command Execution Order

命令执行顺序

Quick Reference

快速参考

Common Operations

常见操作

Searching for errors in the last hour

搜索过去一小时内的错误追踪数据

✅ CORRECT — scoped to one service, narrow time window, error filter on

✅ 正确 — 限定单个服务、窄时间窗口、启用错误过滤器

❌ WRONG — no service, no error filter, huge result set

❌ 错误 — 未指定服务、无错误过滤器、结果集过大

Searching for slow traces

搜索慢追踪数据

✅ CORRECT — slow checkout traces in the last hour

✅ 正确 — 过去一小时内的慢结账追踪数据

✅ CORRECT — narrow further by operation when you know the endpoint

✅ 正确 — 已知端点时进一步按操作缩小范围

❌ WRONG — listing everything and sorting client-side wastes the API budget

❌ 错误 — 列出所有数据后在客户端排序会浪费API配额

Fetching a full trace

获取完整追踪数据

✅ CORRECT — list to discover trace ids, then get the one of interest

✅ 正确 — 先列出追踪数据发现trace id，再获取目标详情

❌ WRONG — oodle traces get without an id (it expects the id as a positional arg)

❌ 错误 — oodle traces get需要传入id（它将id作为位置参数）

Time window flags

时间窗口参数

✅ CORRECT

✅ 正确

❌ WRONG — human strings are not parsed

❌ 错误 — 不解析自然语言字符串

Best Practices

最佳实践

Always specify --service to scope the search

始终指定--service来限定搜索范围

✅ CORRECT

✅ 正确

❌ WRONG — full-tenant scan

❌ 错误 — 全租户扫描

Use --error to find failing traces, not client-side filtering

使用--error查找失败的追踪数据，而非客户端过滤

✅ CORRECT

✅ 正确

❌ WRONG — fetches every trace then filters client-side

❌ 错误 — 获取所有追踪数据后在客户端过滤

Use --min-duration to find slow traces, not client-side sort

使用--min-duration查找慢追踪数据，而非客户端排序

✅ CORRECT — server-side filter, returns ~the right number of rows

✅ 正确 — 服务器端过滤，返回数量合适的结果

❌ WRONG — pulls everything, sorts on the client

❌ 错误 — 获取所有数据后在客户端排序

Keep time windows ≤ 24h for list; widen by re-querying, not by raising --to

list命令的时间窗口保持≤24小时；如需扩大范围请重新查询，而非增大--to的范围

✅ CORRECT — bounded window

✅ 正确 — 限定窗口

❌ WRONG — multi-day list

❌ 错误 — 多天范围的列表

Failure Handling

故障处理

References

参考资料

❌ WRONG —
`oodle traces get`
without an id (it expects the id as a positional arg)

❌ 错误 —
`oodle traces get`
需要传入id（它将id作为位置参数）

Always specify
`--service`
to scope the search

始终指定
`--service`
来限定搜索范围

Use
`--error`
to find failing traces, not client-side filtering

使用
`--error`
查找失败的追踪数据，而非客户端过滤

Use
`--min-duration`
to find slow traces, not client-side sort

使用
`--min-duration`
查找慢追踪数据，而非客户端排序

Keep time windows ≤ 24h for
`list`
; widen by re-querying, not by raising
`--to`

`list`
命令的时间窗口保持≤24小时；如需扩大范围请重新查询，而非增大
`--to`
的范围