oodle-traces

Oodle 追踪记录 — 搜索与分析

本技能教 Agent 如何使用合适的服务、时间和时长筛选条件搜索 Oodle 追踪记录，按 ID 获取完整追踪详情，以及运行 TraceQL。

前提条件

brew install oodle-ai/oodle/oodle
oodle configure

确认追踪记录端点正常工作（使用近期时间范围）：

oodle traces list --start -15m --end now -o json | jq 'length'

命令执行顺序

运行任何 oodle 命令之前：

1. 检查上下文中是否已有服务名称和大致时间范围。
2. 如果没有，运行 oodle traces label-values resource::service.name --start -1h --end now -o json，以发现近期产生过追踪记录的服务。
3. 使用 --service、--start、--end 以及以下选项中的至少一个构建搜索条件：--tags '{"span_status":"Error"}'、--min-duration 或 --operation。如果要筛选任意 span 属性，请使用 oodle traces traceql search。
4. 如需检查单条追踪记录，运行 oodle traces get <trace-id> --start -1h --end now -o json。
5. 在生产环境中，不要在没有 --service 筛选条件的情况下运行 oodle traces list。

快速参考

任务	命令
列出某个服务的追踪记录	oodle traces list --service <svc> --start -1h --end now -o json
仅列出错误追踪记录	oodle traces list --service <svc> --tags '{"span_status":"Error"}' --start -1h --end now -o json
列出慢速追踪记录（>500ms）	oodle traces list --service <svc> --min-duration 500ms --start -1h --end now -o json
按操作筛选	oodle traces list --service <svc> --operation GET_/users --start -1h --end now -o json
获取完整追踪记录	oodle traces get <trace-id> --start -1h --end now -o json
TraceQL 搜索	oodle traces traceql search '{ status = error }' --start -1h --end now
TraceQL 指标	oodle traces traceql metrics '{ status = error } | rate() by (resource.service.name)' --start -1h --end now --step 1m

常见操作

搜索过去一小时内的错误

# ✅ CORRECT — scoped to one service, narrow time window, error filter on
oodle traces list --service api --tags '{"span_status":"Error"}' --start -1h --end now -o json

# ❌ WRONG — no service, no error filter, huge result set
oodle traces list --start -1h --end now -o json

搜索慢速追踪记录

# ✅ CORRECT — slow checkout traces in the last hour
oodle traces list --service checkout --min-duration 500ms --start -1h --end now -o json

# ✅ CORRECT — narrow further by operation when you know the endpoint
oodle traces list --service checkout --operation POST_/cart --min-duration 500ms --start -1h --end now -o json

# ❌ WRONG — listing everything and sorting client-side wastes the API budget
oodle traces list --service checkout --start -1h --end now -o json | jq '.data | sort_by(.spans[0].duration) | reverse | .[0:10]'

获取完整追踪记录

# ✅ CORRECT — list to discover trace ids, then get the one of interest
TRACE_ID=$(oodle traces list --service api --tags '{"span_status":"Error"}' --start -15m --end now -o json | jq -r '.data[0].traceID')
oodle traces get "$TRACE_ID" --start -1h --end now -o json

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

# ❌ WRONG — `oodle traces get` without --start and --end (both are required)
oodle traces get "$TRACE_ID" -o json

时间范围标志

--start 和 --end 是 list 和 get 的必需参数。它们接受与 CLI 其他部分相同的格式：

格式	示例
Epoch 秒	1731628800
RFC 3339	2026-01-02T00:00:00Z
now	now
相对时长	-1h、-30m、-7d

# ✅ CORRECT
oodle traces list --service api --start -30m --end now -o json

# ❌ WRONG — human strings are not parsed
oodle traces list --service api --start "30 minutes ago"

TraceQL

oodle traces traceql 的别名是 oodle traces tql。请将查询放在单引号中，避免 shell 更改 {、}、" 或 !。

# Find traces (filter only; a metrics query is rejected)
oodle traces traceql search '<filter>' [--start -1h] [--end now] [--limit 20]

# Time series from spans (needs a metrics function; a plain filter is rejected)
oodle traces traceql metrics '<filter> | <function>' [--start -1h] [--end now] [--step 5m] [--exemplars N] [-o graph|stats|json]

# Attribute names and values (reads only the last hour; no --start/--end)
oodle traces traceql tags [--scope resource|span|intrinsic|all] [-q '<filter>']
oodle traces traceql tag-values <tag> [-q '<filter>']

标志	含义
--start、--end	search 和 metrics：默认值为 -1h 和 now。
--limit	search：追踪记录的最大数量（默认值为 20）。
--step	metrics：30s、5m、1h、1d 或秒数。默认值为 1m，并会适当增大，以确保每个序列不超过 300 个点。
--exemplars	metrics：示例追踪记录的最大数量。仅在使用 -o json 或 -o yaml 时显示。
-q、--query	tags、tag-values：仅查看符合此筛选条件的 span。

输出：search 每条追踪记录输出一行；-o json 会附加匹配的 span 和属性。metrics 每个序列输出一行（点数、最后值、最小值、最大值、平均值）；-o graph 绘制终端图表，-o stats 提供摘要，-o json 提供所有数据点。

支持的语法

部分	支持
Spanset 过滤器	{ <condition> }
属性范围	resource.<name>、span.<name> 和未限定范围的 .<name>（匹配 span 或资源）
内置属性	name、status、duration、kind
比较	= != =~ !~ > >= < <=
在一个 spanset 中组合	&&、`
spanset 的并集	`{ A }
属性存在／不存在	span.foo != nil、span.foo = nil
字面量	字符串 "x"、数字、时长 10s 250ms、status = error / ok / unset、kind = server / client / internal / producer / consumer
指标函数	rate()、count_over_time()、avg_over_time(<field>)、min_over_time(<field>)、max_over_time(<field>)、sum_over_time(<field>)、histogram_over_time(<field>)、quantile_over_time(<field>, 0.5, 0.95, ...)
分组	指标函数后接 by (<attribute>, ...)

暂不支持

语法	替代用法
标量过滤器：{ ... } | count() > 2、| avg(duration) > 1s	使用 count_over_time() 或 avg_over_time() 运行 traceql metrics，并读取结果
{ A } && { B }（同一条 trace 中的两个不同 span）	当一个 span 必须同时匹配两项时，使用一个 spanset { A && B }
结构运算符 >>、<<、~	分别搜索每个 span，然后比较 trace id
parent. 和 link. 范围	使用 span. 或 resource. 属性
rootName、traceDuration	使用单个 span 的 name 和 duration（例如，根据名称查找根 span）
直接存在性判断：{ span.foo }	{ span.foo != nil }

如果查询因“not supported”而失败，请根据上表改写。不要告诉用户 TraceQL 不可用。

示例

# Errors in one service
oodle traces traceql search '{ resource.service.name = "checkout" && status = error }' --start -1h --limit 20

# GenAI tool calls over 10 s
oodle traces traceql search '{ span.gen_ai.tool.name != nil && duration > 10s }' --start -24h --limit 50

# Error rate by service
oodle traces traceql metrics '{ status = error } | rate() by (resource.service.name)' --start -6h --step 5m

# p50 and p95 latency per route, as a terminal chart
oodle traces traceql metrics '{ kind = server } | quantile_over_time(duration, 0.5, 0.95) by (span.http.route)' --start -1h -o graph

# Error rate with 5 example traces, for drill-down
oodle traces traceql metrics '{ status = error } | rate()' --start -1h --exemplars 5 -o json

# Attribute names and values
oodle traces traceql tags --scope span
oodle traces traceql tag-values span.http.route -q '{ resource.service.name = "checkout" }'

监控运行的是 PromQL，而不是 TraceQL。要针对 trace 发出告警，请在 oodle_trace_metrics 指标上编写监控查询；对于 GenAI span，则在 oodle_genai_* 指标上编写（参见 oodle-monitors 技能）。

最佳实践

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

Trace 数量可能非常庞大；未经过滤的列表开销很高，也会受到速率限制。

# ✅ CORRECT
oodle traces list --service api --start -1h --end now -o json

# ❌ WRONG — full-tenant scan
oodle traces list --start -1h --end now -o json

使用 --tags 查找失败的 trace，而不是在客户端过滤

--tags '{"span_status":"Error"}' 会将谓词交给服务端处理，更快返回匹配结果。

# ✅ CORRECT
oodle traces list --service api --tags '{"span_status":"Error"}' --start -1h --end now -o json

# ❌ WRONG — fetches every trace then filters client-side
oodle traces list --service api --start -1h --end now -o json | jq '.data[] | select(.spans[].tags[] | .key=="error")'

使用 --min-duration 查找耗时较长的 trace，而不是在客户端排序

# ✅ CORRECT — server-side filter, returns ~the right number of rows
oodle traces list --service api --min-duration 500ms --start -1h --end now -o json

# ❌ WRONG — pulls everything, sorts on the client
oodle traces list --service api --start -1h --end now -o json | jq '.data | sort_by(.spans[0].duration) | reverse'

将 list 的时间窗口保持在 ≤ 24h；通过重新查询扩大范围，而不是调低 --start

查询 7 天的列表会返回过多行，并有超时风险。按小时分页。

# ✅ CORRECT — bounded window
oodle traces list --service api --tags '{"span_status":"Error"}' --start -1h --end now -o json

# ❌ WRONG — multi-day list
oodle traces list --service api --tags '{"span_status":"Error"}' --start -7d --end now -o json

故障处理

错误	原因	修复方法
401 Unauthorized	API 密钥无效或缺失	运行 oodle configure 或设置 OODLE_API_KEY
404 Not Found	Trace ID 不存在或已超出保留期限	使用较近的 --start 重新列出，以查找当前的 trace id
connection refused	OODLE_DEPLOYMENT URL 错误	检查 OODLE_DEPLOYMENT 环境变量
结果为空	服务名称错误，或时间范围超出保留期限	列出最近的服务：oodle traces label-values resource::service.name --start -1h --end now；如果 --start 超出保留期限，请缩短偏移量；如果时间范围太短，请扩大范围（CLI 会显示读取的范围）
请求超时	时间范围过大或未筛选服务	缩小 --start/--end 范围，添加 --service，添加 --min-duration 或 --tags
429 Too Many Requests	并发获取 trace	添加 --retries 3；将请求频率限制在每秒低于 5 次
required flag(s) "end", "start" not set	list 和 get 需要同时设置这两个标志	添加 --start -1h --end now
--min-duration 返回 400	时长未指定单位	使用 500ms、2s
TraceQL ... is not supported	使用了“尚不支持”部分中的语法	按该表中的替代写法重写
search 拒绝查询	查询包含指标函数（| rate() …）	使用 oodle traces traceql metrics
metrics 拒绝查询	查询不包含指标函数	添加指标函数，或使用 oodle traces traceql search

参考资料

• Oodle CLI 仓库
• Oodle 文档
• OpenTelemetry trace 概念
• TraceQL