mcpField
O
otel-relay-query

otel-relay-query

github.com/editframe开发1969 次安装2 周前更新
代码仓库

关于 otel-relay-query

这份指南介绍如何在渲染分析中查询 otel-relay 收集的本地 OpenTelemetry spans，供开发者检查 trace 并验证埋点。

主要功能

  1. 01查看 span 与 trace 概况
  2. 02按服务、名称或时间筛选 trace
  3. 03按名称和属性查询 span
  4. 04获取单条 trace 的全部 span
  5. 05清除 span 存储与 SSE 缓冲区

适用场景

  1. 01确认渲染 span 是否发出
  2. 02生产 trace 缺失时检查本地埋点
  3. 03比较快慢任务的 trace
  4. 04按 render 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 span，并通过实时 SSE 流和可查询的 HTTP API 对外提供这些数据。在渲染分析期间，使用查询 API 查找特定 span、比较 trace，并验证埋点，无需加载整个缓冲区。

查询 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

Span 数量、trace 数量、服务名称和时间范围。首先使用此端点确认是否有 span 到达。

GET /api/traces

Trace 列表，按时间倒序排列。可选查询参数：?service=、?name=（根 span 名称包含的内容）、?from= / ?to=（Unix 毫秒）、?limit=（默认 50）。

GET /api/traces/{traceId}

某个 trace 的所有 span，按开始时间排序。返回 { traceId, spans: [...] }。

GET /api/spans

匹配的 span 列表。查询参数：

  • ?name= — 精确匹配 span 名称
  • ?namePrefix= — 前缀匹配（例如 SegmentEncoder）
  • ?traceId= — 某个 trace 中的所有 span
  • ?attr.{key}={value} — 属性筛选，可重复使用（例如 ?attr.renderId=abc&attr.jobId=xyz）
  • ?from= / ?to= — Unix 毫秒时间范围
  • ?limit= — 默认 100，最大 1000
DELETE /api/buffer

清除 span 存储和 SSE 环形缓冲区。每次测试渲染前运行，以获得干净的基线。

常见用法

检查 SegmentEncoder span 是否到达 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"

获取特定渲染作业的完整 trace

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

按属性查找某次渲染的所有 span

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

比较快速与缓慢的 trace

# 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 路径）都会将 span 索引到 SpanStore 中。三个辅助索引——按 traceId、span 名称以及属性键+值建立——可让 QuerySpans 在筛选前选取选择性最高的索引，即使缓冲区达到 50k span 上限，查询也能保持快速。Span 按 spanId 去重，并在达到上限时按先进先出（FIFO）顺序淘汰。

SpanStore 与 SSE 环形缓冲区并行；通过 DELETE /api/buffer 清除其中一个时，另一个也会同时清除。

来源：telecine/services/otel-relay/store.go、api.go。

何时使用此技能

在本地运行渲染且需要以下操作时使用：

  • 验证是否正在发出特定 span（例如 SegmentEncoder.renderFrame、ElectronEngine.captureFrame）
  • 通过确认埋点在本地正常工作，诊断生产环境中缺失的 trace
  • 比较快速和缓慢作业的 span 结构
  • 在基准测试运行期间测量冷启动率（rpcReady 是否存在）或 GCS 写入开销

评论

支持 Markdown