SuperAPI AI 工具集

logging-best-practices

数据与分析

查看项目

更新于 10-15 18:37

技能介绍

用途:为应用日志实现提供指南,核心是宽事件(canonical log lines)模式——每个请求、每个服务只发出一个上下文丰富的结构化事件,用于调试与分析。

适用时机:编写或审查日志代码、添加 console.log 或 logger.info、为新服务设计日志策略、搭建日志基础设施时。

主要能力与原则:

  1. 宽事件(关键):不在处理函数中分散打日志,而是在请求完成时(finally 块)汇总为单个结构化事件,包含 method、path、requestId、timestamp、status_code、outcome、duration_ms 等。
  2. 高基数与高维度(关键):包含用户 ID、请求 ID 等高基数字段,以及每事件多字段的高维度,便于按用户查询并回答未预料的问题。
  3. 业务上下文(关键):包含订阅层级、购物车金额、功能开关、账户年龄等,目标是知道“某高级客户未能完成 2499 美元购买”而非仅“结账失败”。
  4. 环境特征(关键):每个事件包含 commit hash、服务版本、区域、实例 ID,便于关联部署与定位区域问题。
  5. 单一 logger(高):启动时配置一个 logger 实例并全局导入,保证格式一致与环境上下文自动附加。
  6. 中间件模式(高):由中间件处理计时、状态、环境与事件发出,处理函数只添加业务上下文。
  7. 结构与一致性(高):统一 JSON 格式、跨服务字段名一致、简化为 info 与 error 两个级别、禁止非结构化字符串。

应避免的反模式:每请求多次 console.log;多文件使用不同 logger 实例;缺少环境上下文;缺少业务上下文;非结构化字符串;跨服务 schema 不一致。

规则文件:wide-events.md、context.md、structure.md、pitfalls.md,分别覆盖宽事件、上下文、结构与常见陷阱。

限制:资料未提供具体安装命令、平台支持范围、收费信息或效果数据,暂未提供。