SuperAPI AI 工具集

logging-best-practices

通用与其它

查看项目

更新于 10-16 08:39

技能介绍

用途:为应用日志实现提供规范,重点推广宽事件(又称规范日志行)模式——每个请求、每个服务只发出一个上下文丰富的结构化事件,而非分散多条日志,从而支持强大的调试与分析。

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

核心原则:一是宽事件(关键),在请求完成时于 finally 块中统一发出单个结构化事件,包含方法、路径、请求 ID、时间戳、状态码、结果、耗时等;二是高基数与高维度(关键),包含用户 ID、请求 ID 等海量唯一值字段及众多字段,便于按用户查询并回答未预料的问题;三是业务上下文(关键),始终记录订阅层级、购物车金额、功能开关、账户年龄等,目标是知道“某高级客户未能完成 2499 美元购买”而非仅“结账失败”;四是环境特征(关键),每个事件包含提交哈希、服务版本、区域、实例 ID,便于关联部署与区域问题;五是单一日志器(高),启动时配置一个实例并全局导入;六是中间件模式(高),由中间件处理计时、状态、环境与发出,处理器只添加业务上下文;七是结构与一致性(高),统一使用 JSON、字段名跨服务一致、简化为 info 与 error 两级、禁止记录非结构化字符串。

应避免的反模式:每请求多条分散日志、多日志器实例、缺少环境上下文、缺少业务上下文、非结构化字符串、跨服务字段模式不一致。

规则文件涵盖宽事件、上下文、结构、常见陷阱四部分,强调每服务跳发出一个宽事件、用请求 ID 串联、在 finally 中发出、支持高基数与高维度字段、始终传播请求 ID。参考资料包括 Logging Sucks、Observability Wide Events 101 与 Stripe 的 Canonical Log Lines。具体安装或调用命令暂未提供。