worker-rs-otel:为 Cloudflare Workers 手写 OpenTelemetry OTLP 导出层
worker-rs-otel:为 Cloudflare Workers 手写 OpenTelemetry OTLP 导出层
在 Macro 的文档协同链路里,services/sync-service 运行在 Cloudflare Workers 的 wasm 沙箱中,却需要把 span 与日志送进外部 OTLP 采集器。标准 opentelemetry-otlp 导出器依赖后台线程和长驻运行时,在 wasm Workers 里无法工作,因此仓库内独立出一个 worker-rs-otel crate,用「手写缓冲 + 每次调用 flush + waitUntil 保活」的方式补齐这条上报通路。本文以 crates/worker-rs-otel/AGENTS.md 为主线,结合源码逐层拆解它的模块划分、配置开关、span 生命周期、proto 映射与 traceparent 传播。
设计出发点:为什么必须"手写"导出器
AGENTS.md 对定位说得很明确:这是「Cloudflare Workers(worker-rs)的 OpenTelemetry tracing 支持」,而且「OTLP 传输/缓冲/flush 是手写实现的,因为 wasm Workers 无法使用常规的 opentelemetry-otlp exporter」。
从源码结构看,这一约束体现在三个具体的取舍上:
- 没有后台批处理线程:
opentelemetry_sdk的 batch processor 依赖线程与定时器;Workers 的 isolate 只在请求期间存活,因此缓冲被放在thread_local!里(src/exporter.rs),由请求结束时的显式 flush 驱动。 - 不引入 gRPC/tonic 传输:虽然依赖了
opentelemetry-proto的gen-tonic-messages,但只使用它生成的消息类型来做序列化,实际发送走worker::Fetch的 HTTP POST(src/exporter.rs)。 - 异步任务需要保活:Workers 的
waitUntil正好提供"响应已返回但 isolate 仍可执行"的语义,crate 用WaitUntiltrait 把它抽象出来(src/lib.rs)。
Cargo 清单印证了这个最小依赖集:opentelemetry(开 trace)、opentelemetry-proto(gen-tonic-messages、logs、trace、with-serde)、opentelemetry_sdk(trace)、worker、http、tracing/tracing-subscriber、uuid(js)、web-time,以及带 wasm_js feature 的 getrandom(crates/worker-rs-otel/Cargo.toml)。
模块地图:四个入口各司其职
AGENTS.md 的 "Start here" 给出的四个文件就是理解该 crate 的最短路径:
| 文件 | 职责 | 关键导出 |
|---|---|---|
| src/layer.rs | tracing_subscriber::Layer 实现,span 关闭时落入缓冲 |
OtelLayer、traceparent_for_span |
| src/exporter.rs | thread-local 缓冲、配置读取、flush 到 OTLP | 内部 configure / flush_into |
| src/trace_context.rs | W3C traceparent 解析与注入 |
TRACEPARENT、parse_traceparent、traceparent_from_request 等 |
| src/proto.rs + src/model.rs | 真实 opentelemetry-proto 线格式与内部数据模型 |
export_traces_request / export_logs_request |
lib.rs 把对外能力收束为一小组符号:常量 REMOTE_TRACE_ID_FIELD(值 trace.remote_id)与 REMOTE_PARENT_FIELD(值 trace.remote_parent),trait WaitUntil,函数 scope,以及从 layer / trace_context 重新导出的类型(src/lib.rs)。
关于二进制格式还有一个容易误解的点:AGENTS.md 特意强调 proto.rs / model.rs 使用的是「真实 opentelemetry-proto 线类型,而不是自造 schema」。也就是说,虽然报文以 JSON 发送,但结构由官方 crate 生成,字段编号与语义与 OTLP 规范一致,采集端不需要为 Macro 做特殊解析。
接入方式:以 sync-service 为例
1. 初始化 subscriber 时挂上 Layer
sync-service 在 #<a href="https://link.gitcode.com/i/0aeffc4774d8fe6cd2cae694658e8c26" target="_blank">event(start)] 里构建 subscriber:先建 EnvFilter(sync_service=trace,loro=warn)与 JSON 格式的 fmt layer,再在 wasm32 分支上追加 OtelLayer([services/sync-service/src/lib.rs):
#[cfg(target_arch = "wasm32")]
{
use tracing_web::{MakeConsoleWriter, performance_layer};
layered
.with(fmt_layer.with_writer(MakeConsoleWriter))
.with(
performance_layer()
.with_details_from_fields(tracing_subscriber::fmt::format::Pretty::default()),
)
.with(worker_rs_otel::OtelLayer::new("sync-service"))
.init();
}
OtelLayer::new 接受一个 &'static str 作为 service.name,它会在序列化时写入 Resource 属性与 InstrumentationScope 名称(src/layer.rs、src/proto.rs)。注意 OtelLayer 只挂在 wasm 分支:非 wasm 构建走普通 fmt 输出,因为本地原生运行时并不需要这条 OTLP 通路。
2. 用 scope 包住一次 Worker 调用
scope 是整个 crate 的调用约定核心:
pub async fn scope<T>(
env: &worker::Env,
wait_until: &impl WaitUntil,
future: impl Future<Output = T>,
) -> T {
exporter::configure(env);
let output = future.await;
exporter::flush_into(wait_until);
output
}
三段语义分别是:
configure(env)从 Worker 环境变量读取上报配置,并写入 thread-local 缓存;await业务 future,其间所有 span 关闭、日志事件都进入缓冲;flush_into(wait_until)把缓冲内容转成 OTLP 请求,挂到waitUntil上异步发送,不阻塞响应。
WaitUntil 对 worker::Context 与 worker::State 都做了实现(src/lib.rs),所以普通 fetch handler 用 Context、Durable Object 内部用 State,调用形式一致。
3. 在 fetch handler 中建立根 span 并接收上游上下文
let traceparent = worker_rs_otel::traceparent_from_request(&req);
let (remote_id, remote_parent) = worker_rs_otel::remote_fields(traceparent.as_ref());
let method = req.method().to_string();
let path = req.path();
let span = tracing::info_span!(
"request",
http.method = %method,
http.path = %path,
trace.remote_id = %remote_id,
trace.remote_parent = %remote_parent,
);
worker_rs_otel::scope(&env, &ctx, router(env.clone(), req).instrument(span)).await
(services/sync-service/src/lib.rs)
remote_fields 把可选的上游 SpanContext 转成 (trace_id_hex, span_id_hex) 字符串对;没有上游上下文时返回两个空字符串(src/trace_context.rs)。这两个值必须以保留字段名写入 span,OtelLayer 才能在 on_new_span 阶段识别并把本 span 接到上游 trace 上。
配置项:两个环境变量决定一切
导出行为由 worker::Env 中的变量控制,configure 只读取一次:
const ENDPOINT_VAR: &str = "OTEL_EXPORTER_OTLP_ENDPOINT";
const ENVIRONMENT_VAR: &str = "ENVIRONMENT";
| 变量 | 作用 | 缺省行为 |
|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT |
OTLP/HTTP 采集器基地址,导出器会自行追加信号路径 | 未设置或为空字符串 → 不导出(traces 与 logs 都跳过) |
ENVIRONMENT |
写入 Resource 的 deployment.environment 属性 |
未设置 → 省略该属性 |
读取逻辑对空字符串做了过滤(.filter(|value| !value.is_empty())),因此把变量设为空等价于关闭(src/exporter.rs)。
端点拼接由 signal_endpoint 完成:去掉尾部 / 后追加 /v1/{signal}(src/exporter.rs),并有对应单测固定这个行为:
#[test]
fn appends_signal_path_to_collector_endpoint() {
assert_eq!(
signal_endpoint("http://otel-collector:4318/", "traces"),
"http://otel-collector:4318/v1/traces"
);
...
}
因此配置时应填写基地址,不要写 /v1/traces,否则会得到重复路径。
services/sync-service/wrangler.toml 提供了三种典型配置:
- 本地开发:
ENVIRONMENT = "local",OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4318",注释说明这是本机 jaeger/datadog-agent 的 OTLP 接收端口,且deployment.environment=local与 Datadog agent 的DD_ENV对齐; - dev / prod:端点指向
https://macro-prox-dev.macroverse.workers.dev/i/otlp与https://macro-prox-prod.macroverse.workers.dev/i/otlp,注释写明「代理注入 Datadog key;导出器只负责追加信号路径」; - 未在部署环境设置该变量即等于关闭导出(services/sync-service/wrangler.toml、#L99-L109、#L140-L150)。
有一个实现细节值得留意:configure 用 if config.is_some() { return; } 做了「首次写入即锁定」的处理(src/exporter.rs)。由于配置存放在 thread-local,同一 isolate 后续的 scope 调用不会重新读环境变量。这在实际部署中通常无感(isolate 生命周期短),但若你在本地热改 wrangler.toml 的变量,需要重启 wrangler dev 才能生效。
Span 生命周期:从 on_new_span 到 on_close
OtelLayer 只实现了 Layer 的四个回调,构成一条完整的 span 状态机(src/layer.rs)。
父上下文决策
on_new_span 先记录字段(FieldVisitor 会把 trace.remote_id / trace.remote_parent 单独解析为字节数组,其余字段原样收集),然后按以下优先级确定 trace:
let (trace_id, parent_span_id, local_root) = match parent {
Some((trace_id, parent_span_id)) => (trace_id, Some(parent_span_id), false),
None => match visitor.remote_trace_id {
Some(remote_trace_id) => (remote_trace_id, visitor.remote_parent, true),
None => (random_trace_id(), None, true),
},
};
即:
- 若存在
tracing父 span,且其扩展中已有LiveSpan,直接继承同一个 trace_id,local_root = false; - 否则若 span 字段带有效的
trace.remote_id,采用上游 trace_id 与可选的trace.remote_parent,并标记为本地根; - 否则生成新的随机 trace_id(
uuid::Uuid::new_v4()的 16 字节),并标记为本地根。
local_root 会在序列化时决定 span 类型:本地根导出为 SpanKind::Server,其余为 SpanKind::Internal(src/proto.rs)。这也解释了为什么入口 span 必须携带 trace.remote_* 字段——它是把外部 trace 与本 isolate 内 trace 缝合起来的唯一入口。
span_id 一律新建,由 random_span_id 取 UUID 的后 8 字节(src/model.rs);时间戳用 web_time 取 Unix 纳秒,避免 wasm 下 std::time::SystemTime 的限制(src/model.rs、#L43-L48)。
运行期字段与事件
on_record:Span::record(...)补录的字段会追加到LiveSpan.attrs,因此tracing::field::Empty占位后再赋值的模式(durable_object.rs中的http.path、document.id、snapshot.bytes)能正确落到导出属性里。on_event:级别低于等于INFO的事件(即ERROR/WARN/INFO)才处理,DEBUG/TRACE被直接丢弃;事件既挂到所属 span 的events列表,又作为独立LogRecord进入日志缓冲;若级别为ERROR且该 span 尚未记录错误信息,则写入error_message(src/layer.rs)。on_close:移除LiveSpan,补齐结束时间、名称、级别与代码位置,推入 span 缓冲(src/layer.rs)。
error_message 在序列化时转成 Status { code: Error, message },其它 span 不带 status(src/proto.rs)。这就是"错误可以直接在 trace 后端按 status 过滤、而不必翻日志"的实现基础。
序列化:字段如何映射到 OTLP
proto.rs 把内部模型翻译成 opentelemetry-proto 类型,映射规则如下:
Span
| 内部字段 | OTLP 字段 |
|---|---|
data.trace_id / span_id / parent_span_id |
trace_id / span_id / parent_span_id(字节向量,无父则为空) |
span.name |
name |
local_root |
kind:Server 或 Internal |
start_ns / end_ns |
start_time_unix_nano / end_time_unix_nano |
attrs |
attributes(全部为字符串 KeyValue) |
| — | 追加 level、code.filepath、code.lineno(行号为 IntValue) |
events |
events[],每个带 time_unix_nano、name、attributes |
error_message |
status.code = Error + message |
| — | flags: 1(采样标记) |
Log
| 内部字段 | OTLP 字段 |
|---|---|
time_ns |
time_unix_nano 与 observed_time_unix_nano |
level |
severity_number(ERROR/WARN/INFO/DEBUG/TRACE 一一对应)+ severity_text |
body |
body(字符串 AnyValue) |
attrs |
attributes,追加 target、code.filepath、code.lineno |
trace_id / span_id |
同名字段;有 trace 时 flags = 1 |
Resource 层两个信号一致:service.name 取自 batch 中第一条记录的 service_name(空 batch 回退为 unknown-service),deployment.environment 来自 ENVIRONMENT;InstrumentationScope 的 name 与 service.name 相同(src/proto.rs、#L156-L185)。
单测 builds_correlated_log_record 验证了这条链路的关键点:WARN 映射到 SeverityNumber::Warn,trace_id/span_id 原样透出,body 为字符串值(src/proto/test.rs)。
缓冲与导出:512 上限与"不阻塞响应"
缓冲是三个 thread-local:SPAN_BUFFER、LOG_BUFFER 与 CONFIG(src/exporter.rs)。写入时做容量判定:
const MAX_BUFFERED_SPANS: usize = 512;
const MAX_BUFFERED_LOGS: usize = 512;
pub(super) fn buffer_span(span: ClosedSpan) {
SPAN_BUFFER.with(|buffer| {
let mut buffer = buffer.borrow_mut();
if buffer.len() < MAX_BUFFERED_SPANS {
buffer.push(span);
}
});
}
这正是 AGENTS.md 在 Gotchas 里点明的行为:「缓冲是 thread-local 且有上限(MAX_BUFFERED_SPANS/MAX_BUFFERED_LOGS = 512);一次超过上限的 Worker 调用会静默丢弃溢出部分」。没有计数、没有告警——设计上把它当作一条"高频请求不应产生海量 span"的硬边界。如果一个请求会打出成百上千条 info!,应改用聚合指标或在源头降级。
flush 的执行顺序值得完整读一遍:
- 用
std::mem::take取走两个缓冲(先清空,避免 flush 期间的日志污染下一批); - 两者皆空则直接返回
None,不产生任何请求; - 读取配置,若
OTEL_EXPORTER_OTLP_ENDPOINT缺失则返回None(数据被丢弃); - 分别为 traces 与 logs 序列化为 JSON,拼出各自端点;
- 返回一个 async 块,traces 先发、logs 后发,任一失败只记一条
tracing::debug!,不重试、不影响另一方。
发送端固定使用 JSON:
async fn post_signal(endpoint: &str, body: String) -> worker::Result<()> {
let mut request = Request::new_with_init(
endpoint,
RequestInit::new().with_method(Method::Post).with_body(Some(body.into())),
)?;
request.headers_mut()?.set("Content-Type", "application/json")?;
let response = Fetch::Request(request).send().await?;
if response.status_code() >= 300 { /* Err */ }
Ok(())
}
也就是说这条通路是 OTLP/HTTP + JSON 编码,接收端必须支持 /v1/traces 与 /v1/logs 的 JSON 变体。这也是 opentelemetry-proto 需要开启 with-serde feature 的原因。
W3C traceparent 传播:三种载体与一个 WebSocket 兜底
trace_context.rs 承担"进"与"出"两个方向。
进:parse_traceparent 借 opentelemetry_sdk::propagation::TraceContextPropagator 从单元素 map 中提取,再用 is_valid() 过滤(src/trace_context.rs)。HeadersLike trait 抽象了载体,已有三个实现:HashMap<String, String>(任意 hasher)、http::HeaderMap、worker::Headers(src/trace_context.rs)。traceparent_from_request 先查请求头,再退化为查 URL 查询参数 traceparent:
pub fn traceparent_from_request(request: &worker::Request) -> Option<SpanContext> {
traceparent_from_headers(request.headers()).or_else(|| {
request.url().ok()?
.query_pairs()
.find(|(key, _)| key == TRACEPARENT)
.and_then(|(_, value)| parse_traceparent(&value))
})
}
查询参数兜底对应的是 WebSocket 场景:浏览器无法自定义 WS 握手头,把 traceparent 放进 URL 是可行的替代方案。常量注释也直说 TRACEPARENT 同时是「W3C trace-context 头与 WebSocket 查询参数」(src/trace_context.rs)。
出:traceparent_for_span 从 registry 中取出该 span 的 LiveSpan,用 TraceFlags::SAMPLED 注入回字符串(src/layer.rs、src/trace_context.rs)。单测直接断言了采样位:
let traceparent = traceparent_for_span(&span).expect("managed span context");
assert!(parse_traceparent(&traceparent).is_some());
assert!(traceparent.ends_with("-01"));
在 sync-service 里,这个能力被用来缝合 Worker 与 Durable Object 之间的跳转:pass_to_session 先建 do.fetch span,再把生成的 traceparent 写进转发请求头(services/sync-service/src/cf_worker.rs);copy_handler 的辅助函数则把原始请求的 traceparent 头原样搬到新子请求上(services/sync-service/src/cf_worker.rs)。DO 侧在 fetch 里用 traceparent_from_request + remote_fields 接回上游,形成一条完整的跨 hop trace(services/sync-service/src/durable_object.rs)。
使用约束:三个必须遵守的规则
1. flush 必须发生在 span 关闭之后、且仍在 scope 内
durable_object.rs 里有一段直接写明动机的注释:
// Log the failure inside the span and the scope: the scope flushes
// telemetry when it ends, and a log buffered after it is only exported
// if a later request on the same isolate happens to flush it.
(services/sync-service/src/durable_object.rs)
实践含义是:所有可能产生日志/span 的工作都要包在 worker_rs_otel::scope(...) 的 future 内部。DO 的 fetch、websocket_message、以及注释提到的其它 handler 都遵循这一模式(scope 内是 .instrument(span) 的业务 future)。若在 scope 返回之后再 warn!,该日志只会躺在 thread-local 缓冲里,能不能被导出取决于同一 isolate 上是否还有下一个请求恰好触发 flush——即"可能丢失"。
2. getrandom 的 wasm_js feature 不能关
AGENTS.md 的 Gotchas 提醒:「getrandom 的 wasm_js feature 必须保持开启——否则 wasm Workers 没有 OS 随机源」。这与实现相呼应:trace_id/span_id 都来自 uuid::Uuid::new_v4()(src/model.rs),而 uuid 在 Cargo 中开启了 js feature,getrandom 显式指定 wasm_js(crates/worker-rs-otel/Cargo.toml)。任何一次依赖收敛把这两个 feature 去掉,都会在 wasm 目标上表现为随机数不可用。
3. 本 crate 的边界:只管 Workers 的 OTLP
AGENTS.md 的 Scope 一节划得很清楚:本 crate 拥有「单次 Cloudflare Worker 调用的 span/日志缓冲与 OTLP 导出,以及 traceparent 传播」;不负责「Rust 服务或浏览器的 OTel」——那些走常规 opentelemetry SDK 或 packages/observability。仓库的观测规范也重申了同一分工:Web 与 Cloudflare Workers 使用 @macro-inc/observability 的 Telemetry 门面,不要直接 import OpenTelemetry,也不要新增第二条上报通路(.agents/rules/observability.md)。因此扩展 instrumentation 时,正确做法是新增 tracing span/字段,而不是在业务代码里再写一个 exporter。
验证与测试
AGENTS.md 给出的检查命令是 cargo test -p worker-rs-otel,并附了前提:SQLX_OFFLINE 需未设置。
SQLX_OFFLINE= cargo test -p worker-rs-otel
四个模块各带一个测试文件,覆盖的正是最容易回归的点:
| 测试 | 验证内容 |
|---|---|
| src/trace_context/test.rs | 合法 traceparent 解析出 trace_id/span_id/采样位;非法值返回 None;HashMap 与 http::HeaderMap 两种载体都能提取 |
| src/layer/test.rs | 受管 span 能生成可解析且采样位为 01 的 traceparent |
| src/proto/test.rs | 日志严重级别映射、trace/span 关联字段、body 编码 |
| src/exporter/test.rs | 端点拼接在带/不带尾斜杠时都正确 |
端到端验证则依赖真实采集器:本地按 wrangler.toml 的默认 env 把 OTEL_EXPORTER_OTLP_ENDPOINT 指向 http://localhost:4318,起一个支持 OTLP/HTTP 的接收端(如 jaeger 或 datadog-agent),跑一次请求后在 trace 后端按 service.name=sync-service 与 deployment.environment=local 检索。仓库的观测规范把这条检查写成了准入标准:改动过的流程要能「在 Tempo 里找到它的 trace,跨服务是一条连通的 trace,各阶段有耗时,且能按实体 ID 检索到 span」(.agents/rules/observability.md)。
小结
worker-rs-otel 用不到 700 行代码解决了 wasm Workers 上一个具体的工程矛盾:既要符合 OTLP 生态(真实 opentelemetry-proto 类型、标准 /v1/traces 与 /v1/logs、W3C traceparent),又不能依赖后台线程与常驻运行时。它的答案是——thread-local 双缓冲 + 每次调用 waitUntil flush + 512 条硬上限 + 失败仅记 debug 日志。理解了 scope 的包裹语义、trace.remote_id / trace.remote_parent 两个保留字段,以及两个环境变量的开关作用,就能在 services/sync-service 之外正确地复用这套基础设施,并避开"日志打在 scope 之外导致丢失"这类隐式陷阱。