第十二篇：《全链路监控与可观测性：前端错误追踪与性能分析》

在生产环境中，前端代码一旦部署上线，就进入了一个"黑盒"------用户访问时发生了什么、哪里慢了、为什么报错，开发者无法直接感知。全链路监控与可观测性将前端从"黑盒"变为"白盒"，让你能够实时了解应用的健康状况、用户体验和潜在问题。2025-2026 年，前端可观测性已从"错误捕获"演进为"全链路追踪 + 用户行为回放 + 结构化日志"的完整体系。本文从前端监控的三大支柱出发，系统讲解错误监控、性能监控与用户行为监控的采集与上报方案，深入分析 Sentry 从错误监控向全链路可观测性平台的演进，以及 OpenTelemetry 在前端的应用，并通过实战代码帮你搭建一套可落地的监控体系。

一、前端监控的三大支柱

前端监控的本质，是将"用户侧发生了什么"转化为"可分析、可追溯、可告警"的数据。与后端可观测性的三大支柱（Logs、Metrics、Traces）相对应，前端监控也围绕三个核心维度展开：

这三个支柱相互关联，共同构成完整的可观测性体系：性能监控告诉你"哪里慢了"，错误监控告诉你"哪里出了错"，用户行为监控告诉你"用户当时在做什么"。

二、错误监控：从"发生了什么"到"为什么发生"

2.1 前端错误的分类与捕获方式

前端错误可以分为三大类，每种错误的捕获方式不同：

基础错误捕获代码：

javascript 复制代码

// 捕获 JS 运行时错误
window.onerror = function (message, source, lineno, colno, error) {
  reportError({
    type: 'js-error',
    message,
    source,
    lineno,
    colno,
    stack: error?.stack
  });
};

// 捕获未处理的 Promise 异常
window.addEventListener('unhandledrejection', function (event) {
  reportError({
    type: 'unhandled-rejection',
    reason: event.reason,
    promise: event.promise
  });
});

// 捕获资源加载错误
window.addEventListener('error', function (event) {
  if (event.target !== window) {
    reportError({
      type: 'resource-error',
      tagName: event.target.tagName,
      src: event.target.src || event.target.href
    });
  }
}, true);

2.2 Source Map 还原：从压缩代码到源码

生产环境的代码通常经过压缩和混淆，错误堆栈中的行号和变量名无法直接对应源码。Source Map 是解决这个问题的关键：

构建时生成 .map 文件，将压缩代码映射回源码

错误上报时，监控平台使用 Source Map 还原原始堆栈

生产环境注意 Source Map 的安全（避免暴露源码）

在 Sentry 中，可以通过 sentry-cli 或构建插件自动上传 Source Map：

bash 复制代码

# 使用 sentry-cli 上传 Source Map
sentry-cli releases files $RELEASE upload-sourcemaps ./dist --url-prefix '~/static/js'

2.3 错误聚合与去重

生产环境中的同一个错误可能被成千上万个用户触发，每条错误单独上报会造成数据爆炸。监控平台需要具备错误聚合能力------根据错误类型、堆栈指纹等信息将相同错误合并，统计影响用户数和发生次数。

Sentry 通过"错误指纹（Fingerprint）"机制实现智能聚合，开发者也可以通过自定义指纹规则控制聚合粒度。

三、Sentry：从错误捕获到全链路可观测性

Sentry 是目前最广泛使用的前端监控平台。根据 2026 年 3 月的 npm 下载数据，@sentry/browser 每周安装量达 1450 万次。

💡 值得注意的是，约一半的 Sentry JavaScript SDK 安装仍停留在 v8 或更早版本。如果你正在使用旧版本，升级到最新版本可以解锁 Session Replay、结构化日志、AI 追踪等新能力。

3.1 Sentry 的能力演进

Sentry 已从最初的"崩溃报告器"演进为完整的可观测性客户端：

Sentry 的核心价值在于将各种数据源关联在一起：一个错误报告可以链接到 Session Replay（看到用户操作过程）和 Trace（看到哪个微服务慢了），从而快速定位根因。

3.2 Sentry 前端 SDK 接入示例

javascript 复制代码

// 以 React 为例
import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: 'https://your-dsn@sentry.io/your-project',
  environment: import.meta.env.MODE,
  release: import.meta.env.VITE_APP_VERSION,
  
  // 性能监控
  tracesSampleRate: 0.1,  // 生产环境 10% 采样
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,  // 错误时全量录制
  
  // 错误上报
  beforeSend(event) {
    // 可在此过滤敏感信息
    return event;
  }
});

// React 错误边界
const MyApp = () => (
  <Sentry.ErrorBoundary fallback={<ErrorPage />}>
    <App />
  </Sentry.ErrorBoundary>
);

3.3 Sentry v11 与 OpenTelemetry 的深度融合

Sentry v11（预计 2026 年夏季发布）在 OpenTelemetry 支持上进行了重大改进：

不再接管 OpenTelemetry 设置：v11 默认不再为大多数 SDK 设置 OpenTelemetry Tracer Provider，而是生成原生的 Sentry Span。

可选的 OpenTelemetry 集成：如果你需要将 Sentry 事件（错误、日志、Cron、指标）关联到 OpenTelemetry Trace，可以通过可选的集成实现。

最小依赖：OpenTelemetry 依赖缩减到仅保留 @opentelemetry/api。

更好的插桩：支持运行时或构建时插桩（基于 Node.js 的 orchestrion-js），使得在 Vercel 和 Netlify 等平台提供商上也能实现完整的追踪。

这意味着你可以在 Sentry 旁边干净地运行自己的 OpenTelemetry 设置，而不会让 Sentry Span 泄漏到你的 pipeline 中。

四、OpenTelemetry 前端集成：统一的可观测性标准

OpenTelemetry（OTel）是 CNCF 的可观测性标准框架，提供统一的 API 来生成、收集和导出遥测数据（Trace、Metrics、Logs）。通过 OTel，前端数据可以与后端服务关联，形成完整的请求链路追踪。

4.1 前端 OTel 集成基础

bash 复制代码

# 安装依赖
npm install @opentelemetry/api @opentelemetry/sdk-trace-web \
  @opentelemetry/instrumentation-document-load \
  @opentelemetry/exporter-trace-otlp-http
初始化 OTel：

javascript
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

// 1. 创建 Tracer Provider
const provider = new WebTracerProvider();

// 2. 配置导出器（将数据发送到 Jaeger、Elastic 等后端）
const exporter = new OTLPTraceExporter({
  url: 'http://your-collector:4318/v1/traces'
});
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

// 3. 注册自动插桩
registerInstrumentations({
  instrumentations: [
    new DocumentLoadInstrumentation(),
    // 也可添加 XMLHttpRequestInstrumentation、FetchInstrumentation
  ],
});

// 4. 设置为全局 Provider
provider.register();

4.2 前后端关联追踪

前端 OTel 集成后，可以通过 Trace Context 传播实现前后端关联：

前端发起请求时，OTel 自动将 traceparent 头注入到请求中

后端服务接收到请求后，提取 traceparent 并继续同一个 Trace

在 Jaeger 或 Grafana 中可以看到从前端到后端的完整调用链

这种能力使得排查"前端慢 → 后端哪个接口慢"的问题变得极其高效。

五、性能监控：Core Web Vitals 采集与上报

5.1 web-vitals 库集成

使用 Google 的 web-vitals 库采集核心性能指标：

javascript 复制代码

import { onLCP, onINP, onCLS, onFCP, onTTFB } from 'web-vitals';

// 采集并上报性能数据
function reportWebVital({ name, value, id, navigationType }) {
  // 发送到监控平台（Sentry、自建后端等）
  navigator.sendBeacon('/api/rum', JSON.stringify({
    name,      // 'LCP' | 'INP' | 'CLS' | 'FCP' | 'TTFB'
    value,     // 数值（毫秒或分数）
    id,        // 唯一标识
    navigationType,
    url: location.pathname
  }));
}

onLCP(reportWebVital);
onINP(reportWebVital);  // INP 自 2024 年起成为 Core Web Vitals
onCLS(reportWebVital);
onFCP(reportWebVital);
onTTFB(reportWebVital);

5.2 性能预算与告警

将性能指标接入监控平台后，可以设置性能预算（Performance Budget）和告警规则：

六、用户行为监控：Session Replay 与录屏回放

Session Replay（会话回放）是前端可观测性的"杀手级功能"------它录下用户的操作过程，让开发者能够"亲眼看到"错误发生时的用户行为。

Sentry 的 Session Replay 特点：

隐私保护：默认对文本和输入内容进行脱敏

关联性：回放与错误、Trace 直接关联

上下文完整：记录 DOM 变化、用户点击、导航和 Console 输出

javascript 复制代码

// Sentry Session Replay 配置
Sentry.init({
  // 录制 10% 的会话（用于采样分析）
  replaysSessionSampleRate: 0.1,
  // 发生错误时 100% 录制
  replaysOnErrorSampleRate: 1.0,
});

七、小结

前端全链路监控与可观测性体系包含三个核心维度：

错误监控：通过 window.onerror、unhandledrejection、框架 Error Boundaries 捕获各类错误，结合 Source Map 还原源码堆栈，实现快速定位和修复。

性能监控：使用 web-vitals 库采集 LCP、INP、CLS 等 Core Web Vitals，设置性能预算和告警。

用户行为监控：通过 Session Replay 录屏回放，还原问题现场。

Sentry 已从错误捕获工具演进为全链路可观测性平台，v11 进一步深化了与 OpenTelemetry 的融合，支持"错误 + 性能 + 日志 + Replay + AI 追踪"的统一观测。OpenTelemetry 提供了统一的可观测性标准，使前端数据能够与后端服务关联，形成完整的请求链路追踪。