- 可观测性
- 后端
【免费下载链接】highlight
highlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.
@highlight-run/cloudflare是 highlight.io 面向 Cloudflare Workers 场景推出的官方可观测性 SDK，用于在 Worker 边缘运行时中采集错误、日志、Trace 与指标。本文以仓库内 sdk/highlight-cloudflare/CHANGELOG.md 的版本记录为主线，结合 sdk.ts、exporter.ts、navigator.ts 等源码实现，完整梳理该 SDK 从 2.1.2 到 3.1.0 的演进脉络，剖析底层 OTLP 数据管道与运行时兼容性设计，并给出当前版本 API 的完整使用方式。读者读完可获得：该 SDK 的版本变更全貌、核心实现原理，以及在 Cloudflare Workers 中接入错误监控、日志与链路追踪的实战能力。
一、先认识这个包：Cloudflare Workers 上的全栈可观测 SDK
@highlight-run/cloudflare是 highlight.io 为 Cloudflare Workers 运行时提供的官方 SDK，核心目标是：在 Worker 环境中跟踪错误与响应，且“对请求处理性能零影响”——正如仓库内快速入门内容（highlight.io/components/QuickstartContent/backend/js/cloudflare.tsx）所述，所有数据上报都借助 Workers 的waitUntil机制异步进行。
包的当前状态（package.json）：
- 名称：
@highlight-run/cloudflare，当前版本3.1.0（与 CHANGELOG 最新条目一致）； - 构建：基于
tsup同时产出cjs/esm两种格式并生成.d.ts类型声明（见 tsup.config.ts）； - 运行时依赖：
@opentelemetry/api、@opentelemetry/sdk-trace-web、@opentelemetry/sdk-metrics、OTLP HTTP 导出器（trace/metrics）与语义约定包； - 开发依赖：
@cloudflare/workers-types与tsup，tsconfig.json中types同样指向@cloudflare/workers-types。
源码目录结构非常精简，仅四个模块，恰好覆盖了 SDK 的全部职责：
| 文件 | 职责 |
|---|---|
| src/index.ts | 对外导出H与HighlightEnv类型 |
| src/sdk.ts | SDK 核心实现：初始化、span 采集、console 日志代理、指标记录 |
| src/exporter.ts | 基于fetch的自定义 OTLP Trace / Metrics 导出器 |
| src/navigator.ts | 为缺少navigator的 Worker 环境注入 polyfill |
二、版本演进全览：CHANGELOG 逐条继承
CHANGELOG.md 记录了从 2.1.2 到 3.1.0 共 9 个版本，按时间倒序排列。下面逐条保留原始变更说明，并在后续小节结合源码展开解读：
| 版本 | 类型 | 变更内容（原文） |
|---|---|---|
| 3.1.0 | Minor | a290c43：修复 Cloudflare SDK 因非法 opentelemetry 类扩展导致的崩溃（fix cloudflare sdk breaking due to invalid opentelemetry class extension） |
| 3.0.0 | Major | 31dc610：将对opentelemetry-sdk-workers的依赖替换为@opentelemetry/sdk-trace-web |
| 2.1.9 | Patch | 依赖更新d3ba444：@highlight-run/opentelemetry-sdk-workers@1.0.8 |
| 2.1.8 | Patch | 5045b23：修复因依赖缺失导致的 opentelemetry 警告 |
| 2.1.7 | Patch | 依赖更新2339697：@highlight-run/opentelemetry-sdk-workers@1.0.7 |
| 2.1.6 | Patch | e7eb5f581：更新 rrweb 至 2.0.15，支持 LWC |
| 2.1.5 | Patch | 062001317：更新依赖 |
| 2.1.4 | Patch | 依赖更新223e47fbd：@highlight-run/opentelemetry-sdk-workers@1.0.4 |
| 2.1.2 | Patch | 依赖更新b55251c0c：@highlight-run/opentelemetry-sdk-workers@1.0.2 |
可见该 SDK 的发展分为两个阶段：2.x 时代围绕社区包@highlight-run/opentelemetry-sdk-workers构建；3.x 时代全面转向 OpenTelemetry 官方 Web SDK 并自行实现边缘环境适配。下文依次深挖。
三、3.0.0 重大变更：告别 opentelemetry-sdk-workers，接入 sdk-trace-web
3.0.0 是 CHANGELOG 中唯一的 Major 版本，变更内容一句话：用@opentelemetry/sdk-trace-web替换opentelemetry-sdk-workers。从源码可以确认这次迁移的落地情况：
依赖层面（package.json）：当前依赖列表中已完全没有
opentelemetry-sdk-workers，取而代之的是@opentelemetry/sdk-trace-web、@opentelemetry/sdk-metrics、@opentelemetry/resources、@opentelemetry/otlp-exporter-base等官方包。CHANGELOG 中 2.x 系列反复出现的@highlight-run/opentelemetry-sdk-workers依赖更新条目（1.0.2 → 1.0.4 → 1.0.7 → 1.0.8）也随之终结。实现层面（src/sdk.ts）：初始化逻辑现在直接使用
@opentelemetry/sdk-trace-web导出的WebTracerProvider、BatchSpanProcessor、AlwaysOnSampler组装 Tracer：
const spanProcessor = new BatchSpanProcessor(exporter, processorOptions) const tracerProvider = new WebTracerProvider({ resource, spanProcessors: [spanProcessor], sampler: new AlwaysOnSampler(), mergeResourceWithDefaults: true, }) trace.setGlobalTracerProvider(tracerProvider)为什么是 Breaking Change：SDK 初始化签名随之改变。当前源码中
init的签名是init(env: HighlightEnv, service?: string, serviceVersion?: string)（sdk.ts），其中HighlightEnv只含HIGHLIGHT_PROJECT_ID与可选的HIGHLIGHT_OTLP_ENDPOINT；而仓库内 docs-content/sdk/cloudflare.md 中仍保留着 2.x 时代的旧式示例（H.init(request, { HIGHLIGHT_PROJECT_ID }, ctx)）。两相对照可以看出：2.x 依赖opentelemetry-sdk-workers时需要把request与ctx一并传入以驱动批处理；3.x 改为纯 Web SDK 后，上下文改由runWithHeaders显式提取，init只需项目 ID 与服务标识。从 2.x 升级到 3.x 的应用必须同步调整初始化调用。资源标识：
Resource中写入highlight.project_id、telemetry.distro.name: '@highlight-run/cloudflare'、telemetry.distro.version，并默认注入ATTR_SERVICE_NAME（未传service时回退为'highlight-cloudflare'），保证上报到后端的数据可被正确归属到项目与服务（sdk.ts）。
四、3.1.0 修复：非法 opentelemetry 类扩展引发的崩溃
3.1.0 是一次 Minor 修复：解决 Cloudflare SDK 因“非法 opentelemetry 类扩展”导致的运行崩溃。结合当前源码，可以推断该问题与边缘运行时缺失浏览器环境 API 密切相关，仓库中已有两类针对性适配：
4.1navigatorpolyfill（navigator.ts）
@opentelemetry/sdk-trace-web内部实现会访问navigator对象，而 Cloudflare Workers 的运行时并不提供该全局对象。sdk.ts的第一行就通过import './navigator'强制先加载 polyfill：该模块用Proxy构造了一个最小化的navigatorshim，提供userAgent: 'Cloudflare/Worker'、platform: 'Cloudflare'，并对未知属性返回undefined，避免后续访问抛错。这正是 3.x 迁移到 Web SDK 后必须补齐的运行时兼容层。
4.2 自定义 fetch 导出器（exporter.ts）
OTLPTraceExporterFetch与OTLPMetricExporterFetch并非直接复用浏览器版 exporter 类，而是以@opentelemetry/exporter-trace-otlp-http/exporter-metrics-otlp-http的构造函数参数类型为契约、用 Workers 的fetchAPI 重新实现：序列化走JsonTraceSerializer.serializeRequest/JsonMetricsSerializer.serializeRequest，随后向目标 URLPOST application/json，根据r.ok回写ExportResultCode.SUCCESS或FAILED。这类“自实现 exporter”从源码结构看，正是为了避免直接继承浏览器 SDK 类在 Worker 环境中产生非法类扩展问题而做的隔离设计。
五、2.x 补丁系列：从依赖更新到运行时告警修复
2.x 的历次 Patch 记录了 SDK 在旧架构（opentelemetry-sdk-workers）下的持续打磨：
- 2.1.2 / 2.1.4 / 2.1.7 / 2.1.9：四次纯粹的上游依赖升级，跟随
@highlight-run/opentelemetry-sdk-workers从 1.0.2 逐步推进到 1.0.8，属于常规跟随性维护； - 2.1.5：
update dependencies，一次笼统的依赖刷新； - 2.1.6：将 rrweb 升级到2.0.15，新增对LWC（Lightning Web Components）的支持。rrweb 是 highlight 会话回放（session replay）体系的核心录制库（仓库根目录的
rrweb/与__generated/rr/rrweb/即其相关产物），说明该版本在 Worker 侧的录制依赖上也同步了前端回放能力； - 2.1.8：修复“因依赖缺失导致的 opentelemetry 警告”。在 OpenTelemetry 体系中，当某个内部依赖未被显式声明时，SDK 会输出告警提示（例如
@opentelemetry/api未对齐）；这一 Patch 本质上是补齐/对齐依赖声明，消除运行期噪音。
这些历史条目也解释了 3.0.0 迁移的动因：与其持续维护一个面向 Workers 的专用 OpenTelemetry 发行包，不如基于官方sdk-trace-web自行封装，从而减少对第三方封装的长期依赖。
六、当前版本（3.x）的完整 API 与实战用法
SDK 对外统一通过H对象暴露能力（src/index.ts）。以下 API 签名与行为均以 src/sdk.ts 源码为准，且与仓库内端到端示例 e2e/cloudflare-worker/src/index.ts 完全一致。
6.1H.init(env, service?, serviceVersion?)
初始化 SDK 并安装 console 日志代理。参数：
| 参数 | 类型 | 说明 |
|---|---|---|
env.HIGHLIGHT_PROJECT_ID | string，必填 | highlight.io 项目 ID，用于路由错误与数据归属 |
env.HIGHLIGHT_OTLP_ENDPOINT | string，可选 | 自定义 OTLP 上报端点，缺省使用常量HIGHLIGHT_OTLP_BASE（https://otel.highlight.io:4318） |
service | string，可选 | 服务名，缺省为'highlight-cloudflare' |
serviceVersion | string，可选 | 服务版本号，缺省为空 |
初始化会完成：设置 W3C 复合传播器（W3CBaggagePropagator+W3CTraceContextPropagator）、装配BatchSpanProcessor（批量上限 100、队列上限 1 000、导出超时 5 000 ms）、创建PeriodicExportingMetricReader，并建立全局 TracerProvider 与 MeterProvider。
6.2H.runWithHeaders(name, headers, cb, options?)
在既有请求上下文中开启一条命名 span，是 Worker 侧实现“链路追踪不打断请求处理”的关键方法：
// 摘自 e2e/cloudflare-worker/src/index.ts H.runWithHeaders('worker', request.headers, doRequest)其内部流程（sdk.ts）：
- 从请求头提取上下文，用
propagation.extract恢复 Trace 上下文（支持与前端 Session 打通）； - 若请求头携带
X-Highlight-Request，取其secureSessionId/requestId前半段写入 span 的highlight.session_id属性； - 执行
cb(span)，若返回值为Response，自动记录http.response.status_code及除set-cookie外的响应头； - 回调抛错时调用
span.recordException并重新抛出；finally中结束 span。
6.3H.consumeError(error)
上报异常。若当前存在活动 span，则直接recordException挂到该 span 上；否则新建名为error的 span 记录异常后结束（sdk.ts）。
6.4H.setAttributes(attributes)
为后续日志/错误附加结构化属性，将传入的键值对 merge 进 Tracer 的Resource；重复键会更新值。示例见 docs-content/sdk/cloudflare.md：
H.init({ HIGHLIGHT_PROJECT_ID: '1' }, 'example-cloudflare-service') console.log('hi!', { hello: 'world' }) H.setAttributes({ my: 'attribute', is: Math.random() }) console.warn('whoa')6.5H.recordMetric(metric)与H.flush()
recordMetric通过meter.createGauge记录数值型指标，并自动附加highlight.session_id、highlight.trace_id与自定义 tags（sdk.ts）。flush依次对tracerProvider与meterProvider执行forceFlush()，适用于在响应返回前确保数据已发出（内部吞掉“无数据可刷”的异常）。
6.6 完整 Worker 接入示例
将上述 API 组合起来，就是仓库 e2e 项目展示的标准接入形态（e2e/cloudflare-worker/src/index.ts）：
import { H } from '@highlight-run/cloudflare' export default { async fetch(request: Request, env: {}, ctx: ExecutionContext) { H.init({ HIGHLIGHT_PROJECT_ID: '1' }, 'e2e-cloudflare-app') try { return await H.runWithHeaders('worker', request.headers, doRequest) } catch (e: any) { H.consumeError(e) throw e } }, }其中doRequest内所有console.log/console.warn都会被自动采集为日志。
七、底层原理：console 代理、OTLP 管道与日志事件
7.1 console 方法的 monkeypatch
init会遍历RECORDED_CONSOLE_METHODS = ['debug', 'error', 'info', 'log', 'warn']（sdk.ts），逐个替换全局 console 方法：调用时通过Error.captureStackTrace抓取调用栈，新建名为highlight.log的 span 并写入log事件，事件属性包括log.message、log.severity、highlight.project_id、exception.stacktrace（序列化的调用栈），以及从入参对象字面量中展开的结构化字段；随后再调用原始 console 方法保证本地输出不受影响。
7.2 完整数据链路
console.* / span.recordException / gauge.record │ ▼ WebTracerProvider / MeterProvider（BatchSpanProcessor / PeriodicExportingMetricReader） │ ▼ OTLPTraceExporterFetch / OTLPMetricExporterFetch（Json 序列化 + fetch POST） │ ▼ https://otel.highlight.io:4318/v1/traces、/v1/metrics（或自定义 HIGHLIGHT_OTLP_ENDPOINT）其中sdk.ts中 trace 导出器配置concurrencyLimit: 100、timeoutMillis: 5_000，与BatchSpanProcessor的maxExportBatchSize: 100、maxQueueSize: 1_000相互配合，在边缘运行时有限的 CPU 时间内完成批量异步上报，从而兑现“对请求处理零影响”的承诺。
八、升级路径与兼容性注意事项
综合 CHANGELOG 与源码现状，给出如下升级要点（均为基于仓库证据的推断与事实）：
- 2.x → 3.0.0（Breaking）：依赖从
opentelemetry-sdk-workers切换为@opentelemetry/sdk-trace-web；初始化方式从H.init(request, env, ctx)调整为H.init({ HIGHLIGHT_PROJECT_ID }, service?, serviceVersion?)，请求上下文改由runWithHeaders提取与注入。仓库内 docs-content/sdk/cloudflare.md 的示例仍为旧式签名，使用时请以 src/sdk.ts 当前实现为准。 - 3.0.0 → 3.1.0（兼容修复）：修复 Worker 环境中非法 opentelemetry 类扩展导致的崩溃，建议所有 3.0.0 用户尽快升级；当前 package.json 版本即 3.1.0。
- 自定义端点：需要自建 OTLP Collector 时，通过
HIGHLIGHT_OTLP_ENDPOINT覆盖默认端点，SDK 会自动拼接/v1/traces与/v1/metrics路径。 - 本地验证：仓库的 e2e/cloudflare-worker 项目内置了
wrangler dev/wrangler deploy脚本，是跑通完整链路的现成参考。
九、在仓库中继续深入
若想进一步研读，推荐从以下路径入手：
- SDK 核心实现：sdk/highlight-cloudflare/src/sdk.ts、exporter.ts、navigator.ts；
- 包配置与构建：package.json、tsup.config.ts；
- 官方 API 文档（注意其中示例偏旧）：docs-content/sdk/cloudflare.md；
- 端到端示例：e2e/cloudflare-worker/src/index.ts、e2e/cloudflare-worker/package.json；
- 快速入门内容：highlight.io/components/QuickstartContent/backend/js/cloudflare.tsx。
结语：从 2.1.2 到 3.1.0，@highlight-run/cloudflare用九次发版完成了一次关键架构转身——抛弃自维护的 Workers OpenTelemetry 发行包，转向官方sdk-trace-web并辅以navigatorpolyfill 与自定义 fetch 导出器。读懂这份 CHANGELOG，也就读懂了在边缘运行时上做好全栈可观测的核心权衡：兼容官方生态，适配边缘差异，异步零阻塞上报。
- 可观测性
- 后端
【免费下载链接】highlight
highlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.
相关推荐
highlight.io React SDK 演进全解析：`@highlight-run/react` 的 ErrorBoundary 能力与版本治理
highlight.io React SDK 演进全解析： @highlight run/react 的 ErrorBoundary 能力与版本治理 导读 本文
可观测性后端深入解析 @highlight-run/node：Highlight 开源全栈监控平台 Node.js SDK 的版本演进与技术架构
深入解析 @highlight run/node：Highlight 开源全栈监控平台 Node.js SDK 的版本演进与技术架构 @highlight ru
可观测性后端highlight.io 官方 JavaScript SDK 全解析：highlight.run、@highlight-run/node 与 @highlight-run/next 的架构与使用指南
highlight.io 官方 JavaScript SDK 全解析：highlight.run、@highlight run/node 与 @highligh
可观测性后端
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
