Node.js / 系统课时

建立日志与错误追踪

建立日志与错误追踪

日志的目标不是记录得越多越好,而是让一次请求失败后能回答“谁发起、走到哪里、改了什么、为什么失败”。本课用一个原生 Node.js HTTP 服务建立访问日志、业务日志和错误日志,并用同一个 requestId 串起完整上下文。

学习目标

  • 为访问、业务与错误日志定义可检索的结构化字段和合适的日志级别。
  • 在一次 HTTP 请求中生成并回传 requestId,让多条日志能够关联到同一现场。
  • 用状态码、耗时、业务对象 ID、错误栈等字段验证日志是否足以定位一次 500 错误。

先定义三类日志和最少字段

访问日志应在响应完成时记录请求结果,至少包含 method、path、status、durationMs 与 requestId。业务日志只记录关键状态变化,例如订单确认;错误日志除了消息,还要保留 name、stack 和对应请求标识。

类型 建议事件名 必需字段 典型级别
访问日志 http_request requestId、method、path、status、durationMs info
业务日志 order_confirmed requestId、orderId、actorId info
错误日志 request_failed requestId、method、path、error.name、error.message、error.stack error

用 requestId 串起访问、业务和错误日志

下面示例保存为 log-server.js,只使用 Node.js 内置模块。服务会接受长度不超过 128 的 x-request-id,否则生成新的 UUID;响应也回写 x-request-id,便于客户端报错时把标识直接提供给排查人员。

js
const http = require('node:http');
const { randomUUID } = require('node:crypto');
const { performance } = require('node:perf_hooks');

function writeLog(level, event, fields = {}) {
  const line = JSON.stringify({
    time: new Date().toISOString(),
    level,
    event,
    ...fields,
  });

  if (level === 'error') console.error(line);
  else console.log(line);
}

const server = http.createServer((req, res) => {
  const url = new URL(req.url, 'http://127.0.0.1');
  const incomingId = req.headers['x-request-id'];
  const requestId =
    typeof incomingId === 'string' && incomingId.length <= 128
      ? incomingId
      : randomUUID();
  const started = performance.now();

  res.setHeader('x-request-id', requestId);

  res.on('finish', () => {
    writeLog('info', 'http_request', {
      requestId,
      method: req.method,
      path: url.pathname,
      status: res.statusCode,
      durationMs: Math.round(performance.now() - started),
    });
  });

  try {
    if (req.method === 'POST' && url.pathname === '/orders/42/confirm') {
      writeLog('info', 'order_confirmed', {
        requestId,
        orderId: '42',
        actorId: 'user-7',
      });
      res.writeHead(204);
      res.end();
      return;
    }

    if (req.method === 'GET' && url.pathname === '/boom') {
      throw new Error('simulated failure');
    }

    res.writeHead(404, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ code: 'NOT_FOUND' }));
  } catch (error) {
    writeLog('error', 'request_failed', {
      requestId,
      method: req.method,
      path: url.pathname,
      error: {
        name: error.name,
        message: error.message,
        stack: error.stack,
      },
    });

    res.writeHead(500, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ code: 'INTERNAL_ERROR', requestId }));
  }
});

server.listen(3000, '127.0.0.1', () => {
  console.log('listening on http://127.0.0.1:3000');
});

启动服务:

bash
node log-server.js

预期输出:

text
listening on http://127.0.0.1:3000

另开终端分别触发一次业务成功和一次服务端错误。curl 只打印状态码,便于稳定核对结果。

bash
curl -s -o /dev/null -w "confirm:%{http_code}\n" -X POST http://127.0.0.1:3000/orders/42/confirm
curl -s -o /dev/null -w "boom:%{http_code}\n" http://127.0.0.1:3000/boom

预期输出:

text
confirm:204
boom:500

服务端会同时产生结构化日志。下面的 <TIME>、<ID1>、<ID2>、<MS> 与 <STACK> 是动态值占位符,实际值会不同;前两行属于成功请求并共享 <ID1>,后两行属于失败请求并共享 <ID2>。

text
{"time":"<TIME>","level":"info","event":"order_confirmed","requestId":"<ID1>","orderId":"42","actorId":"user-7"}
{"time":"<TIME>","level":"info","event":"http_request","requestId":"<ID1>","method":"POST","path":"/orders/42/confirm","status":204,"durationMs":<MS>}
{"time":"<TIME>","level":"error","event":"request_failed","requestId":"<ID2>","method":"GET","path":"/boom","error":{"name":"Error","message":"simulated failure","stack":"<STACK>"}}
{"time":"<TIME>","level":"info","event":"http_request","requestId":"<ID2>","method":"GET","path":"/boom","status":500,"durationMs":<MS>}

让日志进入可追踪的数据流

生产环境通常让应用把结构化日志写到标准输出和标准错误,由容器运行时、systemd 或日志采集代理负责收集、轮转和发送。应用自己长期写单个本地文件,容易遇到磁盘占满、并发轮转和多实例日志分散的问题。

访问日志放在 finish 事件里,可以拿到最终 status 与完整耗时;业务日志应贴近状态真正变更的位置;错误日志则在捕获点记录栈。三类日志共享 requestId,排查时才能从 500 结果回溯到同一次业务操作。

请求 ID 串联访问日志、业务日志和错误追踪的数据流

用一次 500 验证是否真的可定位

验证时不要只看“有没有 error 日志”,而要检查一次失败能否被完整串起来。请求 /boom 后,从响应 JSON 取到 requestId;在日志系统中过滤这个 ID,应同时找到 request_failed 与状态为 500 的 http_request。

错误记录至少应能回答三件事:异常类型是什么、在哪一层抛出、对应哪次请求。业务记录还应能通过 orderId 或其他稳定对象 ID 检索;如果只能全文搜索一段自然语言消息,后续聚合、告警和跨实例排查都会很困难。

上线前再做一次脱敏检查:用包含测试令牌和 Cookie 的请求访问服务,确认日志里没有这些值;然后制造一条可控 500,确认错误追踪系统能按相同栈聚合,并保留 service、environment、release 与 requestId 这类定位字段。

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

目录与阅读设置

阅读设置

17

记录一个想法

建立日志与错误追踪

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

登录哪都通