编写一套 SPA 首屏性能监控埋点方案（含可运行代码与上报格式）

SPA 首屏性能监控埋点方案（SRE 可观测性视角）

一、指标定义与采集时机

| 指标 | 含义 | 采集方式 | 目标（P75） | |------|------|----------|-------------| | TTFB | 服务器首字节时间 | Navigation Timing API | ≤ 200ms | | FCP | 首次内容绘制 | PerformanceObserver(paint) | ≤ 1.8s | | LCP | 最大内容绘制 | PerformanceObserver(largest-contentful-paint) | ≤ 2.5s | | TTI | 可交互时间 | 自计算：长任务间隙 ≥ 50ms | ≤ 3.5s | | CLS | 累积布局偏移 | PerformanceObserver(layout-shift) | ≤ 0.1 | | JS Bundle | 主包加载耗时 | PerformanceResourceTiming | ≤ 1.2s |

二、Vue3 埋点代码（可运行）

// performance-tracker.js
// 使用: import { initPerfTracker } from './performance-tracker'

const SAMPLE_RATE = 0.1; // 10% 采样，线上可配
const BATCH_SIZE = 10;   // 每批上报条数
const MAX_RETRY = 3;

function shouldSample() {
  return Math.random() < SAMPLE_RATE;
}

function getNavigationTiming() {
  const nav = performance.getEntriesByType('navigation')[0];
  if (!nav) return null;
  return {
    ttfb: Math.round(nav.responseStart - nav.requestStart),
    dns: Math.round(nav.domainLookupEnd - nav.domainLookupStart),
    tcp: Math.round(nav.connectEnd - nav.connectStart),
    ssl: Math.round(nav.secureConnectionStart > 0
      ? nav.connectEnd - nav.secureConnectionStart : 0),
    download: Math.round(nav.responseEnd - nav.responseStart),
    domReady: Math.round(nav.domInteractive - nav.startTime),
    domComplete: Math.round(nav.domComplete - nav.startTime),
  };
}

function observeLCP(cb) {
  const observer = new PerformanceObserver((list) => {
    const entries = list.getEntries();
    if (entries.length > 0) {
      const last = entries[entries.length - 1];
      cb(Math.round(last.startTime), last.element?.tagName?.toLowerCase() || 'unknown');
    }
  });
  observer.observe({ type: 'largest-contentful-paint', buffered: true });
  return observer;
}

function observeFCP(cb) {
  const observer = new PerformanceObserver((list) => {
    const entries = list.getEntries();
    for (const e of entries) {
      if (e.name === 'first-contentful-paint') {
        cb(Math.round(e.startTime));
      }
    }
  });
  observer.observe({ type: 'paint', buffered: true });
  return observer;
}

function observeCLS(cb) {
  let cls = 0;
  const observer = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      if (!entry.hadRecentInput) {
        cls += entry.value;
      }
    }
    cb(Math.round(cls * 1000) / 1000);
  });
  observer.observe({ type: 'layout-shift', buffered: true });
  return observer;
}

function estimateTTI() {
  // 基于 Long Task API：最后一个 >50ms 长任务结束时间
  return new Promise((resolve) => {
    let lastLongTaskEnd = 0;
    const observer = new PerformanceObserver((list) => {
      const entries = list.getEntries();
      for (const e of entries) {
        if (e.duration > 50) {
          lastLongTaskEnd = Math.max(lastLongTaskEnd, e.startTime + e.duration);
        }
      }
    });
    observer.observe({ type: 'longtask', buffered: true });
    // 页面 load 后 5s 取最终值
    setTimeout(() => {
      observer.disconnect();
      resolve(Math.round(lastLongTaskEnd) || null);
    }, 5000);
  });
}

function getBundleTiming() {
  const scripts = performance.getEntriesByType('resource')
    .filter(r => r.initiatorType === 'script' || r.initiatorType === 'link');
  if (!scripts.length) return null;
  const main = scripts.reduce((a, b) => b.transferSize > a.transferSize ? b : a);
  return {
    size: Math.round(main.transferSize / 1024), // KB
    loadTime: Math.round(main.duration),
    url: main.name.split('/').pop(),
  };
}

export function initPerfTracker() {
  if (!shouldSample()) return;

  const data = {
    ts: Date.now(),
    url: location.pathname,
    screen: `${screen.width}x${screen.height}`,
    dpr: devicePixelRatio,
    net: navigator.connection?.effectiveType || 'unknown',
    ua: navigator.userAgent.slice(0, 80),
  };

  data.nav = getNavigationTiming();
  observeFCP(v => { data.fcp = v; });
  observeLCP((v, el) => { data.lcp = v; data.lcpEl = el; });
  observeCLS(v => { data.cls = v; });
  estimateTTI().then(v => { data.tti = v; });
  setTimeout(() => { data.bundle = getBundleTiming(); flush(); }, 5000);
}

// 批量上报（带离线缓存 + 重试）
let buffer = [];
function flush() {
  if (buffer.length < BATCH_SIZE) return;
  const batch = buffer.splice(0, BATCH_SIZE);
  send(batch, 0);
}
function send(batch, attempt) {
  navigator.sendBeacon(
    '/api/perf/batch',
    JSON.stringify({ points: batch, ver: '1.0' })
  ).catch(() => {
    if (attempt < MAX_RETRY) {
      setTimeout(() => send(batch, attempt + 1), 2000 * (attempt + 1));
    }
  });
}

三、上报格式（JSON Schema）

{
  "ver": "1.0",
  "points": [{
    "ts": 1719000000000,
    "url": "/home",
    "screen": "390x844",
    "dpr": 3,
    "net": "4g",
    "ua": "Mozilla/5.0 (iPhone; CPU OS 17_0",
    "ttfb": 180,
    "fcp": 1240,
    "lcp": 1890,
    "lcpEl": "IMG",
    "tti": 2350,
    "cls": 0.042,
    "nav": { "dns": 12, "tcp": 35, "ssl": 18, "download": 85, "domReady": 1100, "domComplete": 1650 },
    "bundle": { "size": 182, "loadTime": 430, "url": "main.abc123.js" }
  }]
}

四、后端存储与 Grafana 面板

存储：推荐 VictoriaMetrics（单二进制、PromQL 兼容），metric 命名 perf_{indicator}_{unit}：

• perf_ttfb_ms、perf_fcp_ms、perf_lcp_ms、perf_tti_ms
• perf_cls_ratio、perf_bundle_size_kb、perf_bundle_load_ms

Grafana 面板建议（4 行 × 2 列）：

1. P50/P75/P95 折线（按 url 维度分组，7d 窗口）
2. LCP 分布直方图（分桶：<1s / 1-2.5s / 2.5-4s / >4s，颜色绿黄红黑）
3. CLS 热力图（按 url × 小时）
4. Bundle 大小趋势（按版本 tag 标记发布点）

五、告警规则（Prometheus / VictoriaMetrics PromQL）

# LCP P75 超 2.5s 持续 5min（对应 Web Vitals "Poor"）
histogram_quantile(0.75,
  sum(rate(perf_lcp_ms_bucket[5m])) by (le, url)
) > 2500

# CLS P75 超 0.1
histogram_quantile(0.75,
  sum(rate(perf_cls_ratio_bucket[10m])) by (le)
) > 0.1

# TTFB 突增（环比 1h 前涨幅 > 50%）
avg_over_time(perf_ttfb_ms{url="/home"}[5m])
  / avg_over_time(perf_ttfb_ms{url="/home"}[1h] offset 1h)
  > 1.5

六、SRE 落地 Checklist

| 项 | 说明 | |----|------| | 采样率灰度 | 上线首日 1% → 3 天无异常提至 10% → 稳定后 5% | | 网络降级 | sendBeacon 失败自动入 sessionStorage，下次 load 重传 | | 隐私合规 | 不上报完整 UA / 经纬度；IP 在网关层脱敏 | | 发布关联 | 上报 body 带 buildId，Grafana 面板用 annotation 标记版本 | | 容量估算 | 10% 采样 × 10 万 DAU ≈ 1 万条/天 × 300B ≈ 3MB/天，VictoriaMetrics 单节点轻松承载 |

七、开放讨论

这个方案刻意把「采集端轻量、服务端聚合」的分界线画在 sendBeacon 处——前端只采原始值，不做任何分位数计算。我见过太多团队在前端 JS 里算 P95 然后上报一个数，结果丢了一条采样整条曲线就断了。你们线上是前端算好分位再上报，还是全量原始值丢给后端聚合？各有什么坑？