可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载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 上的全栈可观测 SDKhighlight-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与tsuptsconfig.json中types同样指向cloudflare/workers-types。源码目录结构非常精简仅四个模块恰好覆盖了 SDK 的全部职责文件职责src/index.ts对外导出H与HighlightEnv类型src/sdk.tsSDK 核心实现初始化、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.0Minora290c43修复 Cloudflare SDK 因非法 opentelemetry 类扩展导致的崩溃fix cloudflare sdk breaking due to invalid opentelemetry class extension3.0.0Major31dc610将对opentelemetry-sdk-workers的依赖替换为opentelemetry/sdk-trace-web2.1.9Patch依赖更新d3ba444highlight-run/opentelemetry-sdk-workers1.0.82.1.8Patch5045b23修复因依赖缺失导致的 opentelemetry 警告2.1.7Patch依赖更新2339697highlight-run/opentelemetry-sdk-workers1.0.72.1.6Patche7eb5f581更新 rrweb 至 2.0.15支持 LWC2.1.5Patch062001317更新依赖2.1.4Patch依赖更新223e47fbdhighlight-run/opentelemetry-sdk-workers1.0.42.1.2Patch依赖更新b55251c0chighlight-run/opentelemetry-sdk-workers1.0.2可见该 SDK 的发展分为两个阶段2.x 时代围绕社区包highlight-run/opentelemetry-sdk-workers构建3.x 时代全面转向 OpenTelemetry 官方 Web SDK 并自行实现边缘环境适配。下文依次深挖。三、3.0.0 重大变更告别 opentelemetry-sdk-workers接入 sdk-trace-web3.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组装 Tracerconst spanProcessor new BatchSpanProcessor(exporter, processorOptions) const tracerProvider new WebTracerProvider({ resource, spanProcessors: [spanProcessor], sampler: new AlwaysOnSampler(), mergeResourceWithDefaults: true, }) trace.setGlobalTracerProvider(tracerProvider)为什么是 Breaking ChangeSDK 初始化签名随之改变。当前源码中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.1navigatorpolyfillnavigator.tsopentelemetry/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.tsOTLPTraceExporterFetch与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.5update dependencies一次笼统的依赖刷新2.1.6将 rrweb 升级到2.0.15新增对LWCLightning 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_IDstring必填highlight.io 项目 ID用于路由错误与数据归属env.HIGHLIGHT_OTLP_ENDPOINTstring可选自定义 OTLP 上报端点缺省使用常量HIGHLIGHT_OTLP_BASEhttps://otel.highlight.io:4318servicestring可选服务名缺省为highlight-cloudflareserviceVersionstring可选服务版本号缺省为空初始化会完成设置 W3C 复合传播器W3CBaggagePropagatorW3CTraceContextPropagator、装配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.mdH.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与自定义 tagssdk.ts。flush依次对tracerProvider与meterProvider执行forceFlush()适用于在响应返回前确保数据已发出内部吞掉“无数据可刷”的异常。6.6 完整 Worker 接入示例将上述 API 组合起来就是仓库 e2e 项目展示的标准接入形态e2e/cloudflare-worker/src/index.tsimport { 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 方法的 monkeypatchinit会遍历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 / MeterProviderBatchSpanProcessor / PeriodicExportingMetricReader │ ▼ OTLPTraceExporterFetch / OTLPMetricExporterFetchJson 序列化 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.0Breaking依赖从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.0highlight-run/cloudflare用九次发版完成了一次关键架构转身——抛弃自维护的 Workers OpenTelemetry 发行包转向官方sdk-trace-web并辅以navigatorpolyfill 与自定义 fetch 导出器。读懂这份 CHANGELOG也就读懂了在边缘运行时上做好全栈可观测的核心权衡兼容官方生态适配边缘差异异步零阻塞上报。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐highlight.io React SDK 演进全解析highlight-run/react 的 ErrorBoundary 能力与版本治理highlight.io React SDK 演进全解析 highlight run/react 的 ErrorBoundary 能力与版本治理 导读 本文可观测性后端深入解析 highlight-run/nodeHighlight 开源全栈监控平台 Node.js SDK 的版本演进与技术架构深入解析 highlight run/nodeHighlight 开源全栈监控平台 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可观测性后端上一篇CANN ops-transformer 环境部署实战CANNLab、Docker 与手动安装三种方案全解下一篇彩虹外链网盘三步打造个人专属文件管理与分享平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
