错误监控与可观测性

应用上线后，你看不到用户屏幕上发生了什么——某个页面白屏了？API 响应变慢了？支付流程中断了？没有监控的应用就像闭着眼睛开车。可观测性（Observability）让你在问题发生时第一时间知道、快速定位原因、在用户投诉之前修复。本章系统讲解 Next.js 应用的错误监控、性能追踪、日志管理和告警策略。

1. 可观测性的三大支柱

1.1 Logs、Metrics、Traces

三者的关系：

• Metrics 告诉你"有问题"（错误率上升）
• Logs 告诉你"什么问题"（具体错误信息）
• Traces 告诉你"为什么有问题"（哪个环节慢了/出错了）

1.2 Next.js 的可观测性挑战

Next.js 的架构让可观测性比传统 SPA 更复杂：

1.3 可观测性工具全景

2. Sentry 集成

2.1 为什么 Sentry 是 Next.js 错误监控的首选

2.2 Sentry 在 Next.js 中的架构

浏览器（Client Components）
├── 未捕获异常 → Sentry 自动捕获
├── React Error Boundary → Sentry 自动上报
├── Console Errors → 可选捕获
└── Performance → 自动追踪路由、Web Vitals

服务端（Server Components / API Routes）
├── 未捕获异常 → Sentry 自动捕获
├── Server Action 错误 → 自动上报
├── 数据库查询错误 → 手动或自动捕获
└── Performance → 自动追踪 API 耗时

边缘（Middleware）
├── 运行时错误 → Sentry Edge SDK 捕获
└── 超时错误 → 自动上报

2.3 Sentry 核心配置要点

2.4 Sentry Tunnel：绕过广告拦截器

很多广告拦截器会屏蔽 sentry.io 的请求，导致客户端错误丢失。解决方案——Sentry Tunnel：

正常模式：
  浏览器 ──→ https://o123.ingest.sentry.io/... ← 被广告拦截器屏蔽

Tunnel 模式：
  浏览器 ──→ https://yourdomain.com/api/sentry-tunnel ──→ sentry.io
  广告拦截器不会屏蔽你自己域名的请求

在 Next.js 中创建 /api/sentry-tunnel Route Handler，将请求转发到 Sentry。

2.5 有效的错误上报

不是所有错误都值得上报——区分信号和噪音：

配置 beforeSend 过滤无用错误：

过滤规则：
1. 忽略已知的第三方脚本错误（Google Analytics、Facebook SDK）
2. 忽略网络错误（用户离线）
3. 忽略浏览器扩展引发的错误
4. 忽略爬虫触发的错误
5. 对重复错误去重（相同 fingerprint）

3. 性能监控

3.1 Web Vitals 监控

3.2 Next.js 内置性能追踪

Next.js App Router 内置了 OpenTelemetry 支持，自动生成以下 Span：

3.3 Server Timing API

Server Timing 是一个 HTTP 头，允许服务端将性能数据传递到浏览器 DevTools：

Server-Timing: db;dur=23.5, render;dur=45.2, total;dur=120.0

浏览器 DevTools 的 Network 面板中可以直接看到每个环节的耗时，无需额外工具。

3.4 性能预算

CI 中强制执行预算：构建时检查 Bundle 大小，超出预算则构建失败。

4. 日志管理

4.1 结构化日志

非结构化日志（不推荐）：

User john logged in from 192.168.1.1 at 2025-04-12T10:30:00Z

结构化日志（推荐）：

{
  "level": "info",
  "event": "user.login",
  "userId": "john",
  "ip": "192.168.1.1",
  "timestamp": "2025-04-12T10:30:00Z",
  "requestId": "req_abc123"
}

结构化日志的优势：

• 可以被日志系统索引和搜索
• 可以按字段过滤（userId = "john"）
• 可以聚合分析（每小时登录次数）
• 机器可读，支持自动化告警

4.2 日志级别

4.3 请求上下文传递

每个请求应该有一个唯一的 requestId，贯穿所有日志——方便从一条错误日志追溯整个请求链路。

请求进入（Middleware）→ 生成 requestId
    ↓
Server Component → 日志包含 requestId
    ↓
API 调用 → 日志包含 requestId
    ↓
数据库查询 → 日志包含 requestId
    ↓
所有日志都可以通过 requestId 关联起来

4.4 日志平台选型

4.5 Vercel Log Drain

Vercel 的 Log Drain 功能可以将所有日志实时转发到外部平台：

Next.js 应用（Vercel）
├── Serverless Function Logs
├── Edge Function Logs
├── Build Logs
└── Static File Access Logs
    ↓
Log Drain → 实时转发到
├── Axiom
├── Datadog
├── BetterStack
└── 自定义 HTTP 端点

5. OpenTelemetry

5.1 为什么需要 OpenTelemetry

OpenTelemetry（OTel）是可观测性的开放标准——由 CNCF 维护，厂商无关。

5.2 Next.js 的 OTel 支持

Next.js 内置了 OpenTelemetry 的实验性支持。配置后，Next.js 自动生成：

5.3 OTel 架构

Next.js 应用
├── 自动探针（HTTP、fetch、Next.js 内部）
├── 手动 Span（自定义业务逻辑追踪）
└── OpenTelemetry SDK
    ↓
OTel Collector（可选，聚合 + 转发）
    ↓
├── Jaeger（链路追踪可视化）
├── Prometheus（指标存储）
├── Grafana Tempo（链路存储）
├── Datadog（商业 APM）
└── Honeycomb（商业分析）

5.4 手动 Span 的使用场景

自动探针覆盖了 HTTP 和 fetch，但业务逻辑需要手动追踪：

6. 告警策略

6.1 告警金字塔

         页面告警（PagerDuty 电话）     ← 严重：服务宕机
        /                          \
      紧急告警（Slack + 短信）         ← 高：错误率飙升
     /                              \
   警告告警（Slack 通知）              ← 中：性能下降
  /                                  \
 信息通知（Dashboard）                 ← 低：趋势变化

6.2 告警规则设计

6.3 告警反模式

6.4 SLO/SLI 驱动的告警

基于 SLO（服务等级目标）设定告警，而非基于绝对阈值：

这种方式的好处：不是"API 慢了就告警"，而是"API 慢到影响用户承诺了才告警"。

7. 监控 Dashboard 设计

7.1 四层 Dashboard

7.2 Next.js 应用的核心 Dashboard

8. 事故响应

8.1 事故响应流程

告警触发
    ↓
值班人响应（< 5 分钟）
    ↓
评估影响范围
├── 全站不可用 → P1（立即全员响应）
├── 核心功能受损 → P2（30 分钟内修复）
├── 非核心功能受损 → P3（4 小时内修复）
└── 性能下降 → P4（下一个工作日修复）
    ↓
定位原因（Traces + Logs + Metrics）
    ↓
修复或回滚
    ↓
事后复盘（Postmortem）

8.2 Postmortem 模板

8.3 混沌工程

主动制造故障来验证监控和告警是否有效：

本章小结

• 可观测性三支柱：Logs（发生了什么）+ Metrics（整体状态）+ Traces（为什么出问题）
• Sentry：Next.js 错误监控首选，覆盖 Client + Server + Edge，配置 Tunnel 绕过广告拦截
• 性能监控：Web Vitals（LCP/INP/CLS）+ Server Timing + 性能预算，CI 中强制执行
• 日志管理：结构化日志 + 请求 ID 关联 + Log Drain 到 Axiom/BetterStack
• OpenTelemetry：厂商无关的可观测标准，Next.js 内置支持，自动追踪路由和 fetch
• 告警策略：严格分级、基于 SLO 驱动、避免告警疲劳
• Dashboard：四层设计（业务/应用/基础设施/依赖），核心关注错误率和 P99 延迟
• 事故响应：5 分钟响应 + 分级处理 + Postmortem 持续改进