真实用户监控与 Web Vitals

Google 的 web-vitals npm 软件包为测量真实用户浏览器中的 Core Web Vitals 提供了简单的 API。请使用 npm install web-vitals 进行安装，并导入各个指标回调函数：onLCP、onFID（已弃用）、onCLS、onFCP、onTTFB，以及用于测量交互到下一次绘制的现代回调 onINP。

每个回调（onLCP、onCLS、onINP 等）都会接收一个指标对象，其中包含：name（'LCP'）、value（毫秒数或无单位分数）、rating（'good'、'needs-improvement'、'poor'）以及 id（用于去重的唯一标识符）。指标值确定后，回调会触发一次。

使用 Navigator.sendBeacon API 或 fetch 将指标报告到您的分析端点。sendBeacon 更为推荐，因为即使页面卸载后它仍会继续运行——这对于 CLS 这类在页面隐藏时才最终确定的指标至关重要。在可能的情况下，请将所有指标报告合并到一个信标中。

要将 Web Vitals 集成到 OpenTelemetry 中，请为每个指标创建仪表型测量工具，例如：const lcp = meter.createObservableGauge('web_vitals.lcp')。在每个 onLCP 回调中，使用相关属性（页面路径、设备类型）记录该值。这样，您的可观测性后端就可以针对 P75 LCP 回退发出警报。

如果要测量 Web Vitals 未捕获的 React 特定性能，请使用用户计时 API：在渲染之前调用 performance.mark('render-start')，之后调用 performance.mark('render-end')，然后调用 performance.measure('component-render', 'render-start', 'render-end')。这些测量结果会显示在 Chrome DevTools 的 Performance 面板中。

React Profiler 组件会包裹一个子树，并通过 onRender 回调提供计时数据：id（Profiler 标识符）、phase（'mount' 或 'update'）、actualDuration（渲染耗时）以及 baseDuration（未使用记忆化时的预计渲染耗时）。请在开发环境中使用它来识别运行缓慢的组件。

可以将未处理的错误和 Promise 拒绝捕获为带有错误状态的 OpenTelemetry 跨度。请设置全局监听器：window.addEventListener('error', handler) 和 window.addEventListener('unhandledrejection', handler)。创建一个跨度，调用 span.setStatus({ code: SpanStatusCode.ERROR })，将错误消息和堆栈追踪作为属性添加，然后结束该跨度。

React 错误边界会捕获组件树中的渲染错误。在 componentDidCatch 方法中，创建一个表示该错误的 OpenTelemetry 跨度，将其状态设置为 ERROR，将 error.message 和 componentStack 作为属性附加，并调用 span.end()。这样，React 渲染错误就会进入您的分布式追踪管道。

经过压缩的生产环境 JavaScript 会生成难以阅读的堆栈追踪，例如 "a.b at bundle.min.js:1:84721"。请在 CI/CD 构建过程中将源映射上传到 Sentry、Datadog 或您的 OpenTelemetry 管道，这样原始堆栈追踪就能自动解析为原始 TypeScript 文件名和行号。

为每个会话发送完整的追踪数据成本很高。请实现会话采样：在首次加载页面时随机分配 sessionSampled 标志，并将其存储在 sessionStorage 中。仅对经过采样的会话初始化 OpenTelemetry SDK 并发送追踪数据（例如采样 10% 的会话）。对于出现错误的会话，始终进行 100% 的采样。

将 Web Vitals 作为 OpenTelemetry 指标报告后，就可以基于 SLO 发出警报：如果在 1 小时窗口内，超过 5% 的会话的 P75 LCP 超过 2.5 秒，就触发警报。这样，工程团队可以获得直接关联用户体验的可执行信号，而不是只能依赖后端基础设施指标。

web-vitals 库中的 onLCP 回调何时触发？

web-vitals 库为在真实用户浏览器中测量 LCP、INP、CLS、FCP 和 TTFB 提供了简单的回调。请将这些指标作为 OpenTelemetry 指标进行报告，以便基于 SLO 发出警报；通过全局监听器和 React 错误边界将错误捕获为 OpenTelemetry 跨度，并上传源映射以解析经过压缩的堆栈追踪。对会话进行采样，以管理数据量，同时保留 100% 的错误覆盖率。