用途:为应用日志实现提供指南,核心是宽事件(canonical log lines)模式——每个请求、每个服务只发出一个上下文丰富的结构化事件,用于调试与分析。
适用时机:编写或审查日志代码、添加 console.log 或 logger.info、为新服务设计日志策略、搭建日志基础设施时。
主要能力与原则:
- 宽事件(关键):不在处理函数中分散打日志,而是在请求完成时(finally 块)汇总为单个结构化事件,包含 method、path、requestId、timestamp、status_code、outcome、duration_ms 等。
- 高基数与高维度(关键):包含用户 ID、请求 ID 等高基数字段,以及每事件多字段的高维度,便于按用户查询并回答未预料的问题。
- 业务上下文(关键):包含订阅层级、购物车金额、功能开关、账户年龄等,目标是知道“某高级客户未能完成 2499 美元购买”而非仅“结账失败”。
- 环境特征(关键):每个事件包含 commit hash、服务版本、区域、实例 ID,便于关联部署与定位区域问题。
- 单一 logger(高):启动时配置一个 logger 实例并全局导入,保证格式一致与环境上下文自动附加。
- 中间件模式(高):由中间件处理计时、状态、环境与事件发出,处理函数只添加业务上下文。
- 结构与一致性(高):统一 JSON 格式、跨服务字段名一致、简化为 info 与 error 两个级别、禁止非结构化字符串。
应避免的反模式:每请求多次 console.log;多文件使用不同 logger 实例;缺少环境上下文;缺少业务上下文;非结构化字符串;跨服务 schema 不一致。
规则文件:wide-events.md、context.md、structure.md、pitfalls.md,分别覆盖宽事件、上下文、结构与常见陷阱。
限制:资料未提供具体安装命令、平台支持范围、收费信息或效果数据,暂未提供。