React / 系统课时

接入日志与监控

接入日志与监控

线上故障通常只给你一个现象:请求变慢、接口报错或用户反馈失败。本节把 Next.js 请求日志、服务端异常和可聚合的运行指标串成一条最小证据链,让一次请求能够被定位、统计并触发后续告警。

学习目标

  • 为 Route Handler 输出可检索、可聚合的结构化请求日志
  • 使用 instrumentation.ts 捕获 Next.js 服务端请求错误
  • 从请求量、错误率和延迟字段建立最小监控与告警信号

先定义一条可关联的证据链

生产日志至少要回答“什么时候、哪个请求、什么结果、耗时多久”。不要只打印自然语言字符串;稳定字段更容易被日志平台解析,再聚合为请求量、错误率和延迟分位数。异常则应额外记录路由上下文和错误类型,但不要写入 Cookie、Authorization 或业务敏感载荷。

Next.js 请求从日志到监控告警的证据链

记录结构化请求日志

下面的 Route Handler 为每次请求生成 requestId,在完成时输出单行 JSON。字段保持低基数:路由、状态码、耗时和请求 ID 足够支撑第一轮排障。

ts
import { randomUUID } from 'node:crypto'

export async function GET() {
  const startedAt = performance.now()
  const requestId = randomUUID()

  const body = { ok: true }

  console.info(JSON.stringify({
    level: 'info',
    event: 'request.complete',
    requestId,
    route: '/api/health',
    method: 'GET',
    status: 200,
    durationMs: Math.round(performance.now() - startedAt),
  }))

  return Response.json(body, {
    headers: { 'x-request-id': requestId },
  })
}

启动项目后请求接口:

bash
curl -s http://localhost:3000/api/health

预期输出:

json
{"ok":true}

服务端终端还会出现一条结构化日志,动态值会因请求不同而变化:

json
{"level":"info","event":"request.complete","requestId":"<ID>","route":"/api/health","method":"GET","status":200,"durationMs":<VALUE>}

requestId 用来串联同一次请求的日志;durationMs 可聚合成 P50、P95 或 P99 延迟。不要把用户 ID、完整 URL 查询串等高基数字段直接做成监控标签,否则成本和查询复杂度都会快速上升。

捕获框架级服务端异常

在项目根目录创建 instrumentation.ts。Next.js 会在服务实例启动时加载该文件,并在框架捕获服务端请求错误时调用 onRequestError。这里先输出结构化错误事件,生产环境可把同样字段发送到你的日志或错误监控平台。

ts
import type { Instrumentation } from 'next'

export const onRequestError: Instrumentation.onRequestError = async (
  err,
  request,
  context,
) => {
  const message = err instanceof Error ? err.message : String(err)
  const digest =
    typeof err === 'object' && err !== null && 'digest' in err
      ? String(err.digest)
      : undefined

  console.error(JSON.stringify({
    level: 'error',
    event: 'request.error',
    message,
    digest,
    path: request.path,
    method: request.method,
    routePath: context.routePath,
    routeType: context.routeType,
  }))
}

这是配置型代码,生效验证方法是让一个测试 Route Handler 主动抛出异常,再确认服务端出现 request.error 事件。若后续改为异步上报错误平台,要在 onRequestError 中等待上报 Promise 完成,避免进程提前结束导致事件丢失。

从日志字段建立最小监控

有了稳定字段后,先监控三个最能反映用户体验的信号:请求量、错误率和延迟。日志平台可以按固定时间窗口统计 request.complete 数量,以 status >= 500 计算错误请求,并对 durationMs 求分位数。

告警阈值要与业务基线绑定,而不是看到单个 500 就报警。例如可以要求“连续多个窗口错误率超过阈值”或“P95 延迟持续恶化”再通知值班人员。这样既能发现真实事故,又能避免偶发错误造成告警风暴。

验收监控链路

上线前至少完成一次受控演练:正常请求应留下 request.complete;故意触发的服务端异常应留下 request.error;监控平台能按路由查看请求量、错误率和延迟趋势;告警消息中能给出时间窗口和路由,而不是只写“应用异常”。

当这些证据可以通过 requestId、路由和时间窗口互相印证时,排障就从“翻日志猜原因”变成了可重复的定位流程。之后再接入 OpenTelemetry、集中式日志或 APM,也应继续保留这套稳定字段和敏感数据边界。

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

目录与阅读设置

阅读设置

17

记录一个想法

接入日志与监控

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

登录哪都通