mcpField
O
otel-relay-query

otel-relay-query

github.com/editframe開発1969 回インストール2 週間前に更新
リポジトリ

otel-relay-query について

レンダリング分析で otel-relay のローカル OpenTelemetry span を調べるためのガイドです。開発者が HTTP API でトレースを確認し、計装を検証できます。

主な機能

  1. 01span とトレースの概要表示
  2. 02サービス、名前、時刻によるトレース絞り込み
  3. 03名前と属性による span 検索
  4. 04トレース内の全 span 取得
  5. 05span ストアと SSE バッファの消去

活用シーン

  1. 01レンダリング span の出力確認
  2. 02本番トレース欠落時のローカル計装確認
  3. 03処理の速い・遅いジョブのトレース比較
  4. 04render ID による span の確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/editframe/skills --skill otel-relay-query

インストール後、Claude Code で/otel-relay-queryを入力して読み込まれたか確認します。

詳細

otel-relay クエリ API

otel-relay は、すべてのローカル telecine サービス（IPC 経由の Electron レンダラーを含む）から OTel スパンを収集し、ライブ SSE ストリームとクエリ可能な HTTP API の両方で公開します。レンダーの分析時にクエリ API を使用すると、全バッファーを読み込まずに特定のスパンを検索したり、トレースを比較したり、計装を検証したりできます。

クエリ API は SSE ストリームと同じポートで動作します（デフォルトは 4319。docker-compose の WORKTREE_TRACING_SSE_PORT で設定します）。別のポートやサービスは不要です。

クイックスタート

# 1. Clear state before a test run
curl -X DELETE http://localhost:4319/api/buffer

# 2. Start a render (via the app or a test script)

# 3. Query what arrived
curl http://localhost:4319/api/summary

エンドポイント

GET /api/summary

スパン数、トレース数、サービス名、時間範囲を返します。まずこれを使って、スパンが届いていることを確認してください。

GET /api/traces

トレースの一覧を新しい順に返します。省略可能なクエリパラメーター：?service=、?name=（ルートスパン名に含まれる文字列）、?from= / ?to=（Unix ミリ秒）、?limit=（デフォルト 50）。

GET /api/traces/{traceId}

1 つのトレースの全スパンを開始時刻順に返します。返される形式は { traceId, spans: [...] } です。

GET /api/spans

条件に一致するスパンのフラットな一覧を返します。クエリパラメーター：

  • ?name= — スパン名の完全一致
  • ?namePrefix= — 前方一致（例：SegmentEncoder）
  • ?traceId= — トレース内のすべてのスパン
  • ?attr.{key}={value} — 属性フィルター。繰り返し指定できます（例：?attr.renderId=abc&attr.jobId=xyz）
  • ?from= / ?to= — Unix ミリ秒の時間範囲
  • ?limit= — デフォルト 100、最大 1000
DELETE /api/buffer

スパンストアと SSE リングバッファーをクリアします。クリーンなベースラインを得るため、テストレンダーごとに実行してください。

よく使うパターン

SegmentEncoder のスパンが Cloud Trace に届いているか確認する

# If these exist locally, missing production spans = exporter/context issue, not missing instrumentation
curl "http://localhost:4319/api/spans?namePrefix=SegmentEncoder&limit=5"
curl "http://localhost:4319/api/spans?namePrefix=ElectronEngine&limit=5"

Electron のコールドスタートのオーバーヘッドを測定する

# rpcReady span is present on cold instances, absent when Electron is reused
curl "http://localhost:4319/api/spans?name=rpcReady"

特定のレンダージョブの完全なトレースを取得する

# traceId comes from Cloud Logging: jsonPayload.workflowId → find matching "Claimed job" log entry
curl "http://localhost:4319/api/traces/{traceId}"

属性でレンダーのすべてのスパンを検索する

curl "http://localhost:4319/api/spans?attr.renderId=6b529000-4b6d-4103-a4e5-3d803dfa64c8"

高速なトレースと低速なトレースを比較する

# List all traces, note the traceIds of slow vs fast jobs
curl "http://localhost:4319/api/traces?limit=20"

# Then pull each trace for comparison
curl "http://localhost:4319/api/traces/{slow-traceId}"
curl "http://localhost:4319/api/traces/{fast-traceId}"

アーキテクチャ

取り込みイベントごとに（gRPC と HTTP OTLP の両方の経路で）、スパンは SpanStore にインデックス化されます。traceId、スパン名、属性のキーと値による 3 つのセカンダリーインデックスにより、QuerySpans はフィルタリング前に最も選択性の高いインデックスを選べるため、バッファー上限の 50k スパンに達してもクエリを高速に処理できます。スパンは spanId で重複排除され、上限に達すると FIFO 方式で削除されます。

SpanStore は SSE リングバッファーと並行して動作します。DELETE /api/buffer を実行すると両方がクリアされます。

ソース：telecine/services/otel-relay/store.go、api.go。

このスキルを使う場面

ローカルレンダーを実行していて、次のことが必要な場合に使用します。

  • 特定のスパン（例：SegmentEncoder.renderFrame、ElectronEngine.captureFrame）が出力されていることを確認する
  • ローカルで計装が機能することを確認し、本番トレースの欠落を診断する
  • 高速ジョブと低速ジョブのスパン構造を比較する
  • ベンチマーク実行中にコールドスタート率（rpcReady の有無）や GCS 書き込みのオーバーヘッドを測定する

コメント

Markdown 対応