SKILL.md
Logging Best Practices Skill
目的
本技能提供应用内日志的实践指南，聚焦 宽事件（canonical log lines）：每个请求、每个服务只发出一条富含上下文的日志事件，便于调试与分析。
适用场景
在以下情况参考本指南：
- 编写或审查日志代码
- 使用
console.log、logger.info等 - 为新服务设计日志策略
- 搭建日志基础设施
核心原则
1. 宽事件（关键）
每个请求、每个服务只发一条富含上下文的日志事件。不要在 handler 里到处打 log，而是在请求结束时汇总为一条结构化事件再输出。
const wideEvent: Record = {
method: 'POST',
path: '/checkout',
requestId: c.get('requestId'),
timestamp: new Date().toISOString(),
};
try {
const user = await getUser(c.get('userId'));
wideEvent.user = { id: user.id, subscription: user.subscription };
const cart = await getCart(user.id);
wideEvent.cart = { total_cents: cart.total, item_count: cart.items.length };
wideEvent.status_code = 200;
wideEvent.outcome = 'success';
return c.json({ success: true });
} catch (error) {
wideEvent.status_code = 500;
wideEvent.outcome = 'error';
wideEvent.error = { message: error.message, type: error.name };
throw error;
} finally {
wideEvent.duration_ms = Date.now() - startTime;
logger.info(wideEvent);
}2. 高基数与高维度（关键）
包含高基数字段（如 user ID、request ID，百万级唯一值）和高维度（每条事件多字段）。便于按用户查询、回答未事先想到的问题。
3. 业务上下文（关键）
始终包含业务上下文：用户订阅档位、购物车金额、功能开关、账号龄等。目标是能知道「一名高级用户未能完成 2499 美元购买」，而不只是「结账失败」。
4. 环境特征（关键）
每条事件包含环境与部署信息：commit hash、服务版本、region、实例 ID。便于把问题与部署关联、定位区域性问题。
5. 单一 Logger（高）
启动时配置一个 logger 实例，全局复用。保证格式一致、自动带上环境上下文。
6. 中间件模式（高）
用中间件处理宽事件基础设施（计时、状态、环境、写出）。Handler 只负责补充业务上下文。
7. 结构与一致性（高）
- 统一使用 JSON 格式
- 跨服务保持字段命名一致
- 简化为两种级别：
info、error - 不记录非结构化字符串
反模式
- 分散日志：一个请求内多次
console.log - 多个 logger：不同文件用不同实例
- 缺环境上下文：无 commit hash、部署信息
- 缺业务上下文：只有技术细节、无用户/业务数据
- 非结构化字符串：
console.log('something happened')而非结构化数据 - schema 不一致：跨服务字段名不统一
指南摘要
宽事件
- 每个服务跳转发一条宽事件
- 包含所有相关上下文
- 用 request ID 串联事件
- 在
finally中、请求结束时发出
上下文
- 支持高基数（userid、requestid）
- 高维度（多字段）
- 始终含业务上下文
- 始终含环境特征（commit_hash、version、region）
结构
- 全代码库使用单一 logger
- 用中间件保证宽事件一致
- 使用 JSON 格式
- 保持 schema 一致
- 仅 info / error 两级
- 不记录非结构化字符串
常见坑
- 避免一个请求多行 log
- 为「未知的未知」设计
- 跨服务传递 request ID