前端链路追踪：用 OpenTelemetry 打通浏览器到服务端的性能数据

前端链路追踪：用 OpenTelemetry 打通浏览器到服务端的性能数据

一、为什么前端需要链路追踪

前端性能监控已经经历了从单纯的页面加载耗时（DOMContentLoaded、load事件）到 Core Web Vitals（LCP、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): Promise<DashboardData> { // 创建自定义 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% 的概率采样，既能覆盖典型路径，又不会在极端流量下对后端存储造成压力。