Vue / 系统课时

前端监控与线上排障

前端监控与线上排障

线上问题难排,通常不是因为缺少日志,而是错误、性能、请求和发布版本彼此断开。本节建立一条从浏览器事件到 release、路由和请求链的最小监控路径,并给出可重复的线上定位顺序。

学习目标

  • 统一采集 Vue 错误、未处理异常、页面性能和异常请求
  • 给监控事件附加 release、路由和请求 ID,形成可关联上下文
  • 按“版本变化 → 前端堆栈 → 请求链 → 修复验证”的顺序排查线上故障

先统一监控事件上下文

每条事件都应带上稳定的 release 标识、当前路由和时间。请求监控再补充方法、路径、状态码、耗时和后端返回的请求 ID。不要采集 Authorization、Cookie、请求体、响应体和完整查询字符串,避免把令牌或个人数据送进监控系统。

下面是片段示例,依赖已有的 Vite + Vue 3 应用;monitoring.ts 作为项目内模块不独立运行。生产环境可以把 /monitor/events 替换成自己的采集入口,并在服务端继续做采样、脱敏和聚合。

ts
import type { App } from 'vue'

type EventKind =
  | 'vue-error'
  | 'window-error'
  | 'promise-rejection'
  | 'navigation'
  | 'request'

interface MonitorEvent {
  kind: EventKind
  release: string
  path: string
  timestamp: string
  message?: string
  stack?: string
  method?: string
  requestPath?: string
  requestId?: string
  status?: number
  durationMs?: number
}

const endpoint = '/monitor/events'
const release = import.meta.env.VITE_APP_VERSION || 'dev'

function toMessage(value: unknown): string {
  if (value instanceof Error) return value.message
  if (typeof value === 'string') return value
  return 'Unknown error'
}

function emit(event: Omit<MonitorEvent, 'release' | 'path' | 'timestamp'>): void {
  const payload: MonitorEvent = {
    ...event,
    release,
    path: location.pathname,
    timestamp: new Date().toISOString()
  }
  const body = JSON.stringify(payload)
  if (import.meta.env.DEV) console.info('[monitor]', payload)
  const sent = navigator.sendBeacon?.(
    endpoint,
    new Blob([body], { type: 'application/json' })
  )
  if (!sent) {
    void fetch(endpoint, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body,
      keepalive: true
    }).catch(() => undefined)
  }
}

export function installMonitoring(app: App): void {
  app.config.errorHandler = (err, _instance, info) => {
    emit({
      kind: 'vue-error',
      message: `${info}: ${toMessage(err)}`,
      stack: err instanceof Error ? err.stack : undefined
    })
  }
  window.addEventListener('error', (event) => {
    emit({
      kind: 'window-error',
      message: event.message,
      stack: event.error instanceof Error ? event.error.stack : undefined
    })
  })
  window.addEventListener('unhandledrejection', (event) => {
    emit({
      kind: 'promise-rejection',
      message: toMessage(event.reason),
      stack: event.reason instanceof Error ? event.reason.stack : undefined
    })
  })
  window.addEventListener('load', () => {
    const nav = performance.getEntriesByType('navigation')[0] as
      | PerformanceNavigationTiming
      | undefined
    if (nav) emit({ kind: 'navigation', durationMs: Math.round(nav.duration) })
  })
}

export async function observedFetch(
  input: RequestInfo | URL,
  init: RequestInit = {}
): Promise<Response> {
  const method =
    init.method ?? (input instanceof Request ? input.method : 'GET')
  const rawUrl = input instanceof Request ? input.url : input.toString()
  const requestPath = new URL(rawUrl, location.origin).pathname
  const startedAt = performance.now()
  try {
    const response = await fetch(input, init)
    const durationMs = Math.round(performance.now() - startedAt)
    if (!response.ok || durationMs >= 1000) {
      emit({
        kind: 'request',
        method,
        requestPath,
        requestId: response.headers.get('x-request-id') || undefined,
        status: response.status,
        durationMs
      })
    }
    return response
  } catch (error) {
    emit({
      kind: 'request',
      method,
      requestPath,
      status: 0,
      durationMs: Math.round(performance.now() - startedAt),
      message: toMessage(error)
    })
    throw error
  }
}

该模块需要在应用启动时安装。下面同样是片段示例,依赖现有 App.vue 和 Vite 入口:

ts
import { createApp } from 'vue'
import App from './App.vue'
import { installMonitoring } from './monitoring'

const app = createApp(App)
installMonitoring(app)
app.mount('#app')

接入后可在开发环境浏览器控制台执行一次可控异常,验证全局错误链路:

js
setTimeout(() => {
  throw new Error('monitor-smoke-test')
}, 0)

预期结果

text
Uncaught Error: monitor-smoke-test
[monitor] <包含 kind="window-error"、release=<VALUE>、path=<PATH> 的事件对象>

同时浏览器会向 /monitor/events 发送 POST。<VALUE> 与 <PATH> 会随实际构建版本和访问路由变化;跨域 API 若要让前端读取 x-request-id,服务端还需要允许该响应头对浏览器脚本可见。

业务 API 层应统一改用 observedFetch,而不是在每个组件重复写监控逻辑。生产环境还应注入不可变的 VITE_APP_VERSION,例如构建号或提交 ID,这样同一错误是否从某次发布开始出现就能被直接聚合。

前端监控事件到线上定位的关联链路

按版本和请求链定位问题

线上排障先缩小范围,再追单个现场。顺序混乱时,很容易在海量日志中反复猜测。

  1. 先按时间窗口和 release 聚合错误率,确认问题是否只出现在某个新版本。
  2. 再按路由、错误信息和堆栈指纹聚类,判断是单页面回归还是全局故障。
  3. 请求失败时,用 requestId、状态码和请求路径去关联网关或后端日志;状态码为 0 通常意味着请求未获得 HTTP 响应,应继续检查网络、跨域或浏览器阻断。
  4. 前端堆栈若来自压缩产物,使用与该 release 一一对应的 source map 还原源码位置。source map 应在 CI 中归档或上传到监控系统,不要让不同 release 共用同一份映射。
  5. 修复上线后用新的 release 重新观察同一错误指纹和请求链,确认错误率下降,而不是只验证“本机不再复现”。

用现象选择第一证据

线上现象 第一证据 优先判断
新版本后 JS 错误陡增 release、堆栈、路由 代码回归、资源缓存不一致
4xx/5xx 请求集中出现 requestId、status、requestPath 鉴权、接口契约、后端异常
页面无报错但明显变慢 navigation/request duration 慢接口、资源加载、网络质量
只有深层 URL 刷新 404 Nginx 访问日志、部署配置 SPA 回退缺失或路径不匹配

修复后验证监控闭环

监控系统自身也可能失效,因此发布验收要包含“事件能否上报”。测试环境至少主动触发一次可控异常和一次失败请求,确认采集端收到正确 release;再检查敏感头、请求体和查询参数没有被记录。

线上修复完成后,不要只看错误条数归零。还要确认新 release 的页面性能没有退化、请求失败率恢复到基线,并保留问题发生版本、影响路由、关联请求 ID、根因和修复版本,下一次同类故障就能直接复用证据链。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

前端监控与线上排障

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通