oodle-traces

Oodle トレース — 検索と分析

このスキルでは、適切なサービス／時間／期間のフィルターを使って 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 のうち少なくとも 1 つを使って検索を組み立てます。任意のスパン属性に対する条件には、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

よく使う操作

過去 1 時間のエラーを検索する

# ✅ 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 のほかの部分と同じ形式を使用できます。

形式	例
エポック秒	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 というエイリアスがあります。シェルによって {、}、"、! が変更されないよう、クエリはシングルクォートで囲んでください。

# 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：このフィルターに一致するスパンのみを対象とします。

出力：search はトレースごとに 1 行を出力します。-o json を指定すると、一致したスパンと属性が追加されます。metrics はシリーズごとに 1 行（ポイント数、最新値、最小値、最大値、平均値）を出力します。-o graph はターミナルにグラフを描画し、-o stats は概要を表示し、-o json はすべてのポイントを出力します。

対応している構文

部分	対応状況
Spanset フィルター	{ <condition> }
属性スコープ	resource.<name>、span.<name>、およびスコープなしの .<name>（span または resource に一致）
組み込み属性	name、status、duration、kind
比較	= != =~ !~ > >= < <=
1 つの 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 }（1 つのトレース内の異なる 2 つの span）	1 つの span が両方に一致する必要がある場合は、1 つの 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" }'

モニターでは TraceQL ではなく PromQL を実行します。トレースに対してアラートを設定するには、oodle_trace_metrics メトリクス、または GenAI span 用の oodle_genai_* メトリクスを対象にモニタークエリを記述します（oodle-monitors スキルを参照）。

ベストプラクティス

検索範囲を絞るため、必ず --service を指定する

トレースの量は膨大になる可能性があります。フィルターなしの一覧はコストがかかり、レート制限の対象になります。

# ✅ 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 を使用する

--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 を使用する

# ✅ 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 の時間範囲は 24 時間以下に保ち、--start を前倒しするのではなく、再クエリで範囲を広げる

7 日分の一覧は行数が多くなり、タイムアウトのリスクがあります。1 時間ごとにページ分割してください。

# ✅ 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	トレース ID が存在しないか、保持期間を過ぎています	最近の --start を指定して再度一覧表示し、現在のトレース ID を探します
接続拒否	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	トレースを同時に取得しています	--retries 3 を追加し、リクエストを 1 秒あたり 5 件未満に制限します
required flag(s) "end", "start" not set	list と get には両方のフラグが必要です	--start -1h --end now を追加します
--min-duration の 400 エラー	期間に単位がありません	500ms、2s を使用します
TraceQL の ... is not supported	「Not supported yet」にある構文です	その表にある置き換え方法を使って書き換えます
search がクエリを拒否する	メトリクス関数（| rate() …）が含まれています	oodle traces traceql metrics を使用します
metrics がクエリを拒否する	メトリクス関数が含まれていません	関数を追加するか、oodle traces traceql search を使用します

参考資料

• Oodle CLI リポジトリ
• Oodle ドキュメント
• OpenTelemetry のトレースの概念
• TraceQL