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,便于客户端报错时把标识直接提供给排查人员。
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');
});启动服务:
node log-server.js预期输出:
listening on http://127.0.0.1:3000另开终端分别触发一次业务成功和一次服务端错误。curl 只打印状态码,便于稳定核对结果。
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预期输出:
confirm:204
boom:500服务端会同时产生结构化日志。下面的 <TIME>、<ID1>、<ID2>、<MS> 与 <STACK> 是动态值占位符,实际值会不同;前两行属于成功请求并共享 <ID1>,后两行属于失败请求并共享 <ID2>。
{"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 结果回溯到同一次业务操作。

用一次 500 验证是否真的可定位
验证时不要只看“有没有 error 日志”,而要检查一次失败能否被完整串起来。请求 /boom 后,从响应 JSON 取到 requestId;在日志系统中过滤这个 ID,应同时找到 request_failed 与状态为 500 的 http_request。
错误记录至少应能回答三件事:异常类型是什么、在哪一层抛出、对应哪次请求。业务记录还应能通过 orderId 或其他稳定对象 ID 检索;如果只能全文搜索一段自然语言消息,后续聚合、告警和跨实例排查都会很困难。
上线前再做一次脱敏检查:用包含测试令牌和 Cookie 的请求访问服务,确认日志里没有这些值;然后制造一条可控 500,确认错误追踪系统能按相同栈聚合,并保留 service、environment、release 与 requestId 这类定位字段。