Highlight 浏览器 SDK 的 OpenTelemetry 实践：内置自动埋点与前后端 Trace 串联

可观测性后端【免费下载链接】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点击查看免费下载本篇聚焦 Highlighthighlight.io 开源全栈监控平台JavaScript SDK 内置的浏览器端 OpenTelemetry 采集能力SDK 如何自动埋点采集页面加载性能、用户交互与网络请求三类前端 Trace如何通过otel.instrumentations配置项精确关闭指定埋点以及如何借助 W3Ctraceparent上下文把服务端 Trace 与浏览器端 Trace 串联成一条完整的调用链。读完后你可以直接把这套配置应用到自己的 Web 应用中获得从鼠标点击到数据库调用的全栈可观测数据。内置浏览器自动埋点采集哪些数据Highlight 的 JavaScript SDK 无需你手动创建 Span即可自动采集浏览器应用所需的 OpenTelemetry 数据。SDK 在初始化时基于 OpenTelemetry 的自动 instrumentation 做额外加工让数据在 Highlight 的 UI 中更具可读性。开箱即用的三类埋点如下页面加载性能Document Load Performance捕获与页面加载相关的时序信息包括 navigation start、DOM content loaded、page load complete 等事件。用户交互User Interactions跟踪点击、表单提交等用户与页面的交互动作。网络请求Network Requests监控 XMLHttpRequest 与 Fetch API 调用提供网络操作性能与成功与否的洞察。在源码中这三类埋点分别由 sdk/highlight-run/src/client/otel/index.ts 中的setupBrowserTracing统一装配默认启用的 instrumentation 为opentelemetry/instrumentation-document-load官方包自定义的UserInteractionInstrumentation实现见 sdk/highlight-run/src/client/otel/user-interaction.tsopentelemetry/instrumentation-fetch与opentelemetry/instrumentation-xml-http-request官方包仅在网络录制开启时启用。Highlight 在此基础上额外注入了一系列自定义属性这是数据在 Highlight UI 里更有用的关键页面加载耗时拆解assignDocumentDurations会把dom_interactive、dom_content_loaded、dom_complete、first_paint、first_contentful_paint、domain_lookup、connect、request、response、load_event、unload等阶段耗时同时以纳秒timings.key.ns和人类可读格式timings.key.readable如12.3ms两个属性写入 documentFetch / documentLoad SpanassignResourceFetchDurations则对每个静态资源请求计算域名解析、连接、请求、响应四段耗时见 index.ts#L512-L603。用户交互属性交互 Span 上会写入event.type、event.tag、event.xpath、event.id、event.text、event.url以及viewport.width/viewport.height鼠标事件还会补充event.x/event.y与相对视口坐标event.relativeX/event.relativeY见 user-interaction.ts#L114-L150。该 instrumentation 是从社区版 OpenTelemetry user-interaction 库移植并针对 Highlight SDK 修改而来同时会 patchhistory.pushState/replaceState等接口当路由发生变化时把 Span 重命名为Navigation: url使前端路由切换在 Trace 中有明确标记见 user-interaction.ts#L430-L484。网络请求增强Span 名称默认是METHOD - /pathname若请求体是 GraphQL querySDK 会解析出操作名把 Span 重命名为QueryName (GraphQL: host/path)并补充graphql.operation.name属性。Span 还会写入清洗后的请求头、请求体、url.full/url.path/url.query以及url.query_params等属性敏感字段按网络录制选项做脱敏或丢弃见enhanceSpanWithHttpRequestAttributesindex.ts#L436-L490。用 otel.instrumentations 关闭指定前端 TraceSDK 的init配置中可以通过otel.instrumentations选项关闭某一类前端 Trace例如禁用用户交互埋点H.init({ // ... otel: { instrumentations: { [opentelemetry/instrumentation-user-interaction]: false } } })从 sdk/highlight-run/src/index.tsx 可以看到options?.otel?.instrumentations被原样透传给setupBrowserTracing在 index.ts 中每项配置的判断逻辑是值不为false即启用因此你既可以不配置全部默认启用也可以按 instrumentation 模块名精确关闭。可选的配置键与默认行为如下表配置键对应能力默认opentelemetry/instrumentation-document-load页面加载性能 SpandocumentLoad / documentFetch / resourceFetch启用opentelemetry/instrumentation-user-interaction用户交互 Span点击、提交、路由导航等启用opentelemetry/instrumentation-fetchFetch API 网络请求 Span仅在networkRecording.enabled为 true 时启用opentelemetry/instrumentation-xml-http-requestXMLHttpRequest 网络请求 Span仅在networkRecording.enabled为 true 时启用也就是说网络请求类埋点与网络录制选项联动只有在开启网络录制的前提下fetch/XHR 的 Span 才会创建并附带请求体、响应体等属性。SDK 底层装配Provider、导出与传播setupBrowserTracingsdk/highlight-run/src/client/otel/index.ts#L73-L297完成了完整的浏览器端 OTel 装配理解这些细节有助于排查采集问题TracerProvider创建WebTracerProviderResource 上写入service.name默认highlight-browser、deployment.environment默认production、highlight.project_id与highlight.session_id后者是 Highlight 将 Span 关联到具体会话的关键。批量导出使用自定义的CustomBatchSpanProcessormaxExportBatchSize: 100、maxQueueSize: 1000、导出超时 5 秒底层 exporter 是支持 XHR 重试的 OTLP HTTP 实现启用 gzip 压缩导出到otlpEndpoint/v1/traces。CustomBatchSpanProcessor会在导出前过滤掉被标记为highlight.record: false的 Span避免无用数据进入队列。指标导出同时创建MeterProviderPeriodicExportingMetricReader周期性把指标发到otlpEndpoint/v1/metrics。调试模式当构建环境DEBUG true时会额外挂一个SimpleSpanProcessor ConsoleSpanExporterSpan 会直接打印到浏览器控制台方便本地验证埋点是否生效。重复初始化保护若检测到 tracerProvider 已存在会打印OTEL already initialized. Skipping...并跳过避免重复 patch 全局对象。串联服务端与客户端 Tracetraceparent 上下文传递SDK 初始化之后应用发出的请求会自动与服务器端的 Trace 连接起来形成从鼠标点击到数据库调用的完整视图前后端映射的更多原理见 全栈映射文档。但方向相反的情形——由服务端发起、且 Span 最终创建在客户端的场景——需要手动传递 trace 上下文。步骤如下在服务端生成 trace 上下文通常是traceparent请求头将该上下文以meta标签的形式写入 HTML 响应Highlight SDK 会自动拾取该 trace 上下文并在客户端侧继续这条 Trace。HTML 中注入上下文的写法为meta nametraceparent content00-${traceId}-${spanId}-${samplingDecision ?? 01} 这里00-是 W3C Trace Context 的版本号前缀samplingDecision缺省取01表示采样。Ruby 服务的现成 Helper部分 SDK 提供了生成这段 HTML 的辅助函数。如果你使用 Highlight 的 Ruby SDK只需在文档head中加入一行% highlight_traceparent_meta %该 Helper 的实现见 sdk/highlight-ruby/highlight/lib/highlight.rb#L314-L338highlight_traceparent_meta生成meta nametraceparent content...标签Helpers.traceparent_meta则返回原始的 traceparent 字符串此外还导出了模块级的Highlight.traceparent_meta/traceparent_meta_tag以及Highlight.traceparent_meta_tag供非 Rails 场景直接使用。仓库中的 Rails 演示应用展示了真实用法模板里紧跟csrf_meta_tags一行即完成注入见 e2e/ruby/rails/demo/app/views/layouts/application.html.erb其中前端H.init同时配置了tracingOrigins: true与otlpEndpoint。服务端如何生成上下文以 Next.js 为例仓库 e2e 用例 e2e/nextjs/pages/api/page-router-trace.ts 演示了服务端侧的标准姿势先通过H.startWithHeaders(page-router-span, {})从请求头恢复/创建 Span随后用 OpenTelemetry API 的propagation.inject(context.active(), headers)把当前上下文注入到发往下游服务的请求头中从而让跨服务调用共享同一条 traceId。任何支持 W3C Trace Context 的服务端 SDKNode、Go、.NET、Ruby 等都能完成同样的读头建 Span 注入头操作。客户端侧CustomTraceContextPropagator 的角色SDK 注册了CustomTraceContextPropagator继承自W3CTraceContextPropagator见 index.ts#L316-L369与W3CBaggagePropagator组成的组合传播器。它的inject逻辑决定了何时向出站请求注入 trace 头若目标 URL 未通过tracingOrigins/urlBlocklist的判定会提前返回、不注入请求头避免把 Highlight 自己上报用的请求backendUrl、otlpEndpoint/v1/traces|logs|metrics也打上 trace 头tracingOrigins为true时默认匹配localhost、同源及相对路径getCorsUrlsPatternindex.ts#L634-L646也可以传入字符串/正则数组自定义匹配范围对于不满足录制条件的请求Span 会被打上highlight.record: false后续在 Span 结束与导出两个环节都会被跳过。也就是说服务端把traceparent放进 HTML 后SDK 用它延续 traceId浏览器侧发出的 API 请求又会通过该传播器携带traceparent头让服务端把数据库、队列等下游 Span 挂到同一条 Trace 之下——双向都打通后从点击到数据库的完整链路才真正成立。小结与适用前提浏览器侧只需正常初始化 Highlight SDK三类自动埋点即生效需要裁剪时用otel.instrumentations按模块名设为false。网络请求 Span 依赖networkRecording.enabled请求头/体的记录范围受网络录制选项如networkHeadersToRedact、bodyKeysToRecord与默认 URL 黑名单约束。前后端 Trace 串联的前提是服务端 SDK 支持 W3C Trace Context并在 SSR 输出中携带traceparentmeta 标签仓库中的 Ruby Rails 演示与 Next.js e2e 用例可作为对照实现直接查阅。以上行为以当前仓库sdk/highlight-run、sdk/highlight-ruby源码为准SDK 升级后配置键名可能调整建议以对应版本的 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点击查看免费下载相关推荐Grafana Tempo 客户端埋点与传播实践从手动/自动/零代码埋点到跨服务 Trace 上下文传递Grafana Tempo 客户端埋点与传播实践从手动/自动/零代码埋点到跨服务 Trace 上下文传递 Instrumentation埋点是 Grafa后端可观测性链路追踪Insanely Fast Whisper 语音转写2 个模型怎么选Insanely Fast Whisper 语音转写2 个模型怎么选 你手头有段两小时的会议录音机器上有 NVIDIA 卡却拿不准该喂给哪个模型完整的人工智能AI AgentAgent 沙箱云原生容器运行时零信任3分钟定位用户行为异常Pinpoint前端埋点与后端关联实战指南3分钟定位用户行为异常Pinpoint前端埋点与后端关联实战指南 你是否还在为用户反馈的页面加载慢而抓狂是否面对海量日志却找不到问题根源Pinpoin后端可观测性APM链路追踪微服务上一篇Helm Dashboard终极故障排查指南快速解决7大常见问题下一篇Seelen UI插件实操指南如何接管任务栏、窗口布局与媒体控制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考