otel-relay-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

otel-relay Query API

otel-relay 查询API

The otel-relay collects OTel spans from all local telecine services (including the Electron renderer via IPC) and exposes them through both a live SSE stream and a queryable HTTP API. Use the query API during render analysis to find specific spans, compare traces, and verify instrumentation without loading the full buffer.

The query API runs on the same port as the SSE stream (default

, set by

WORKTREE_TRACING_SSE_PORT

in docker-compose). No separate port or service required.

otel-relay从所有本地telecine服务（包括通过IPC的Electron渲染器）收集OTel span，并通过实时SSE流和可查询的HTTP API对外暴露。在渲染分析期间使用该查询API，无需加载完整缓冲区即可查找特定span、对比追踪数据并验证埋点。

查询API与SSE流使用相同端口（默认

，由docker-compose中的

WORKTREE_TRACING_SSE_PORT

设置），无需单独端口或服务。

Quick Start

快速开始

bash

undefined

bash

undefined

1. Clear state before a test run

1. 测试运行前清除状态

curl -X DELETE http://localhost:4319/api/buffer

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

2. 启动渲染（通过应用或测试脚本）

3. Query what arrived

3. 查询已收集的数据

curl http://localhost:4319/api/summary

undefined

curl http://localhost:4319/api/summary

undefined

Endpoints

接口

GET /api/summary

GET /api/summary

Span count, trace count, service names, and time range. Use first to confirm spans are arriving.

返回span数量、追踪数量、服务名称和时间范围。可先使用该接口确认span是否已被收集。

GET /api/traces

GET /api/traces

List of traces, most recent first. Optional query params:

?service=

?name=

(root span name contains),

?from=

?to=

(unix ms),

?limit=

(default 50).

返回追踪列表，按时间从新到旧排序。可选查询参数：

?service=

、

?name=

（根span名称包含该值）、

?from=

?to=

（Unix毫秒时间戳）、

?limit=

（默认50）。

GET /api/traces/{traceId}

GET /api/traces/{traceId}

All spans for one trace sorted by start time. Returns

{ traceId, spans: [...] }

返回单个追踪的所有span，按开始时间排序。返回格式为

{ traceId, spans: [...] }

。

GET /api/spans

GET /api/spans

Flat list of matching spans. Query params:

```
?name=
```
— exact span name
```
?namePrefix=
```
— prefix match (e.g.
```
SegmentEncoder
```
)
```
?traceId=
```
— all spans in a trace

?attr.{key}={value}

— attribute filter, repeatable (e.g.

?attr.renderId=abc&attr.jobId=xyz

)

```
?from=
```
/
```
?to=
```
— unix ms time range
```
?limit=
```
— default 100, max 1000

返回匹配的span扁平列表。查询参数：

```
?name=
```
— 精确匹配span名称
```
?namePrefix=
```
— 前缀匹配（例如
```
SegmentEncoder
```
）
```
?traceId=
```
— 返回指定追踪中的所有span

?attr.{key}={value}

— 属性过滤，可重复使用（例如

?attr.renderId=abc&attr.jobId=xyz

）

```
?from=
```
/
```
?to=
```
— Unix毫秒时间范围
```
?limit=
```
— 默认100，最大值1000

DELETE /api/buffer

DELETE /api/buffer

Clears the span store and the SSE ring buffer. Run before each test render for a clean baseline.

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

Common Patterns

常用场景

Check whether SegmentEncoder spans are reaching Cloud Trace

bash

undefined

检查SegmentEncoder span是否已到达Cloud Trace

bash

undefined

If these exist locally, missing production spans = exporter/context issue, not missing instrumentation

如果本地存在这些span，但生产环境缺失，则说明是导出器/上下文问题，而非埋点缺失

curl "http://localhost:4319/api/spans?namePrefix=SegmentEncoder&limit=5" curl "http://localhost:4319/api/spans?namePrefix=ElectronEngine&limit=5"


**Measure Electron cold-start overhead**
```bash

curl "http://localhost:4319/api/spans?namePrefix=SegmentEncoder&limit=5" curl "http://localhost:4319/api/spans?namePrefix=ElectronEngine&limit=5"


**测量Electron冷启动开销**
```bash

rpcReady span is present on cold instances, absent when Electron is reused

rpcReady span仅在冷启动实例中存在，Electron被复用则不存在

curl "http://localhost:4319/api/spans?name=rpcReady"


**Get the full trace for a specific render job**
```bash

curl "http://localhost:4319/api/spans?name=rpcReady"


**获取特定渲染任务的完整追踪数据**
```bash

traceId comes from Cloud Logging: jsonPayload.workflowId → find matching "Claimed job" log entry

traceId来自Cloud Logging：jsonPayload.workflowId → 查找匹配的“Claimed job”日志条目

curl "http://localhost:4319/api/traces/{traceId}"


**Find all spans for a render by attribute**
```bash
curl "http://localhost:4319/api/spans?attr.renderId=6b529000-4b6d-4103-a4e5-3d803dfa64c8"

Compare fast vs slow traces

bash

undefined

curl "http://localhost:4319/api/traces/{traceId}"


**通过属性查找某渲染任务的所有span**
```bash
curl "http://localhost:4319/api/spans?attr.renderId=6b529000-4b6d-4103-a4e5-3d803dfa64c8"

对比快速与慢速追踪数据

bash

undefined

List all traces, note the traceIds of slow vs fast jobs

列出所有追踪，记录慢速与快速任务的traceId

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}"

undefined

curl "http://localhost:4319/api/traces/{slow-traceId}" curl "http://localhost:4319/api/traces/{fast-traceId}"

undefined

Architecture

架构

Spans are indexed in a

SpanStore

on every ingest event (both gRPC and HTTP OTLP paths). Three secondary indexes — by traceId, by span name, by attribute key+value — allow

QuerySpans

to pick the most selective index before filtering, keeping queries fast even at the 50k-span buffer cap. Spans are deduplicated by spanId and evicted FIFO when the cap is hit.

The

SpanStore

is parallel to the SSE ring buffer; clearing one clears both via

DELETE /api/buffer

Source:

telecine/services/otel-relay/store.go

api.go

每次接收数据事件（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

。

When to Use This Skill

使用场景

Use when running a local render and need to:

Verify that specific spans (e.g.

SegmentEncoder.renderFrame

ElectronEngine.captureFrame

) are being emitted

Diagnose missing production traces by confirming the instrumentation works locally
Compare span structure between fast and slow jobs
Measure cold-start rate (
```
rpcReady
```
presence) or GCS write overhead during a benchmark run

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

验证特定span（例如

SegmentEncoder.renderFrame

、

ElectronEngine.captureFrame

）是否已被发送

通过确认本地埋点正常工作，诊断生产环境追踪数据缺失问题
对比快速与慢速任务的span结构
在基准测试期间测量冷启动率（
```
rpcReady
```
是否存在）或GCS写入开销