前端链路追踪用 OpenTelemetry 打通浏览器到服务端的性能数据一、为什么前端需要链路追踪前端性能监控已经经历了从单纯的页面加载耗时DOMContentLoaded、load事件到 Core Web VitalsLCP、INP、CLS的演进。但这两个阶段都有一个共同的盲区它们只能回答用户等了多少毫秒无法回答这毫秒具体消耗在了哪个后端服务、哪个数据库查询上。当一次页面请求慢一秒钟这额外的一秒可能是 CDN 缓存未命中可能是 BFF 层的聚合查询超时可能是某个下游微服务降级。在分布式系统中前端是用户感知性能的最终触点但它同时也是分布式调用的起点。如果不把前端的 Span 和后端的 Span 串联起来性能分析就是盲人摸象。OpenTelemetry 提供的标准 Trace 上下文传播机制恰好解决了这个问题。二、前端到后端的 Trace 串联原理sequenceDiagram participant Browser as 浏览器 participant WebSDK as OTel Web SDK participant App as 前端应用 participant BFF as BFF 层 participant Svc1 as 订单服务 participant Svc2 as 库存服务 participant Collector as OTel Collector participant Jaeger as Jaeger Browser-WebSDK: 创建 Root Span WebSDK-App: 发起 fetch 请求 App-BFF: HTTP traceparent Header BFF-Svc1: gRPC traceparent BFF-Svc2: gRPC traceparent Svc1--BFF: 响应 Svc2--BFF: 响应 BFF--App: 响应 App-WebSDK: Span 结束 WebSDK-Collector: 导出 Span 数据 Svc1-Collector: 导出 Span 数据 Svc2-Collector: 导出 Span 数据 BFF-Collector: 导出 Span 数据 Collector-Jaeger: 聚合存储Trace 上下文的传递核心是 W3C Trace Context 标准。关键载体是traceparent和tracestate两个 HTTP Header。traceparent的格式为00-{trace-id}-{span-id}-{trace-flags}其中trace-id在整个调用链中保持不变span-id在每个环节递增。前端的 OpenTelemetry Web SDK 在发起 fetch 或 XHR 请求时自动注入这些 Header。后端通过 OpenTelemetry 中间件自动解析并创建 Child Span。这样在 Jaeger 或 Grafana Tempo 等后端工具中就能看到从浏览器按钮点击开始一直穿透到数据库查询结束的完整调用瀑布图。三、前端 SDK 的接入与配置前端接入 OpenTelemetry 的核心步骤包括初始化 TracerProvider、配置 Span Processor、注册自动插桩、以及自定义业务 Span。以下是一个生产级别的接入配置// otel-setup.ts — 前端 OpenTelemetry 接入配置 import { WebTracerProvider } from opentelemetry/sdk-trace-web; import { BatchSpanProcessor } from opentelemetry/sdk-trace-base; import { OTLPTraceExporter } from opentelemetry/exporter-trace-otlp-http; import { ZoneContextManager } from opentelemetry/context-zone; import { Resource } from opentelemetry/resources; import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION } from opentelemetry/semantic-conventions; import { FetchInstrumentation } from opentelemetry/instrumentation-fetch; import { registerInstrumentations } from opentelemetry/instrumentation; export function initOpenTelemetry(): void { // 构造资源标识便于在 Jaeger 中按服务和版本过滤 const resource new Resource({ [SEMRESATTRS_SERVICE_NAME]: frontend-web, [SEMRESATTRS_SERVICE_VERSION]: __APP_VERSION__, deployment.environment: __DEPLOY_ENV__, }); // 配置 OTLP 导出器数据发送到后端 Collector const exporter new OTLPTraceExporter({ url: /api/otel/v1/traces, // 通过 BFF 转发避免跨域和暴露 Collector 端口 headers: {}, }); const provider new WebTracerProvider({ resource, // 定义采样策略生产环境建议使用概率采样 // 此处使用父级采样即继承上游采样决策 sampler: undefined, // 默认 AlwaysOn }); // BatchSpanProcessor 批量发送减少网络请求 provider.addSpanProcessor( new BatchSpanProcessor(exporter, { maxQueueSize: 2048, maxExportBatchSize: 512, scheduledDelayMillis: 5000, // 每5秒发送一批 exportTimeoutMillis: 30000, }) ); provider.register({ contextManager: new ZoneContextManager(), // 在异步调用中保持上下文 }); // 注册自动插桩自动为所有 fetch 调用创建 Span registerInstrumentations({ instrumentations: [ new FetchInstrumentation({ propagateTraceHeaderCorsUrls: [ /^https:\/\/api\.example\.com/, /^\/api\//, ], clearTimingResources: true, // 避免 Performance API 资源泄漏 }), ], }); console.log([OTel] 前端链路追踪初始化完成); }自定义 Span 的创建自动插桩只能覆盖 fetch 请求业务逻辑中的关键耗时需要手动创建 Span// custom-span.ts — 自定义业务 Span 示例 import { trace, SpanStatusCode } from opentelemetry/api; const tracer trace.getTracer(frontend-business, 1.0.0); export async function loadUserDashboard(userId: string): PromiseDashboardData { // 创建自定义 Span记录用户仪表盘加载的完整链路 return tracer.startActiveSpan(loadUserDashboard, async (span) { try { // 添加自定义属性便于后续查询过滤 span.setAttribute(user.id, userId); span.setAttribute(component, Dashboard); // 记录内部事件——子步骤标记 span.addEvent(fetch_user_profile_start); const profile await fetchUserProfile(userId); span.addEvent(fetch_user_profile_end); span.addEvent(fetch_recent_orders_start); const orders await fetchRecentOrders(userId); span.addEvent(fetch_recent_orders_end, { orders.count: orders.length, }); span.setStatus({ code: SpanStatusCode.OK }); return { profile, orders }; } catch (error) { span.setStatus({ code: SpanStatusCode.ERROR, message: error instanceof Error ? error.message : 加载仪表盘失败, }); span.recordException(error instanceof Error ? error : new Error(未知错误)); throw error; } finally { span.end(); } }); }四、数据通路架构设计前端直接向 OpenTelemetry Collector 发送数据在生产环境中不推荐——这涉及跨域问题和 Collector 端口的公网暴露风险。推荐的架构是在 BFF 层添加一个转发接口前端通过OTLPTraceExporter将数据以 JSON over HTTP 的格式 POST 到/api/otel/v1/traces。BFF 接收后直接转发到内网的 OpenTelemetry Collector不存储、不解析降低 BFF 开销。Collector 配置batchprocessor 和otlpexporter将数据写入 Jaeger 或 Grafana Tempo。如果使用 CDN需要确保 W3C Trace Context 的 Header 能通过 CDN 正确传递到源站。多数 CDN 默认不会剥离自定义 Header但仍建议在 CDN 配置中显式允许traceparent和tracestate。五、总结前端链路追踪的核心价值在于将用户侧的感知性能和后端的实际耗时串联起来让性能分析从孤立的指标变为完整的调用链视图。OpenTelemetry 通过标准化的 Trace 上下文传播使这一串联成为可能。接入的关键步骤包括初始化 Web SDK 的 TracerProvider 和 Span Processor注册 Fetch 自动插桩为关键业务逻辑创建自定义 Span以及通过 BFF 转发 Trace 数据到 Collector。在采样策略上生产环境建议使用 10%30% 的概率采样既能覆盖典型路径又不会在极端流量下对后端存储造成压力。
