logging-best-practices

日志记录最佳实践技能

版本：1.0.0

目的

此技能提供在应用程序中实现有效日志记录的指南。重点介绍宽事件（也称为规范日志行）模式：每个请求在每个服务中仅发出一个上下文丰富的事件，从而实现强大的调试和分析能力。

适用场景

在以下情况下应用这些指南：

• 编写或审查日志记录代码
• 添加 console.log、logger.info 或类似内容
• 为新服务设计日志记录策略
• 搭建日志记录基础设施

核心原则

1. 宽事件（关键）

每个请求在每个服务中都应发出一个上下文丰富的事件。不要在处理程序中散布多条日志，而应将所有内容整合到一个结构化事件中，并在请求完成时发出。

const wideEvent: Record<string, unknown> = {
  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. 高基数与高维度（关键）

包含高基数字段（用户 ID、请求 ID 等，具有数百万个唯一值）和高维度字段（每个事件包含许多字段）。这样便可按特定用户查询，并回答此前未曾预料的问题。

3. 业务上下文（关键）

始终包含业务上下文：用户订阅等级、购物车金额、功能标志、账户使用时长。目标是了解“高级客户无法完成一笔 2,499 美元的购买”，而不只是“结账失败”。

4. 环境特征（关键）

在每个事件中都包含环境和部署信息：提交哈希、服务版本、区域、实例 ID。这样便可将问题与部署关联起来，并识别特定区域的问题。

5. 单一日志记录器（高）

使用一个在启动时配置的日志记录器实例，并在所有地方导入。这样可以确保格式一致，并自动包含环境上下文。

6. 中间件模式（高）

使用中间件处理宽事件基础设施（计时、状态、环境、事件发出）。处理程序只应添加业务上下文。

7. 结构与一致性（高）

• 始终使用 JSON 格式
• 在各服务间保持字段名称一致
• 将日志级别简化为两个：info 和 error
• 绝不记录非结构化字符串

应避免的反模式

1. 散落的日志：每个请求调用多次 console.log()
2. 多个日志记录器：不同文件中使用不同的日志记录器实例
3. 缺少环境上下文：没有提交哈希或部署信息
4. 缺少业务上下文：只记录技术细节，不包含用户或业务数据
5. 非结构化字符串：使用 console.log('something happened')，而非结构化数据
6. 架构不一致：各服务间字段名称不同

指南

宽事件（rules/wide-events.md）

• 每经过一个服务就发出一个宽事件
• 包含所有相关上下文
• 使用请求 ID 关联事件
• 在请求完成时于 finally 块中发出事件

上下文（rules/context.md）

• 支持高基数字段（user_id、request_id）
• 包含高维度信息（许多字段）
• 始终包含业务上下文
• 始终包含环境特征（commit_hash、version、region）

结构（rules/structure.md）

• 在整个代码库中使用单一日志记录器
• 使用中间件生成一致的宽事件
• 使用 JSON 格式
• 保持架构一致
• 将日志级别简化为 info 和 error
• 绝不记录非结构化字符串

常见陷阱（rules/pitfalls.md）

• 避免每个请求记录多条日志
• 针对未知的未知因素进行设计
• 始终在各服务间传递请求 ID

参考资料：

• Logging Sucks
• Observability Wide Events 101
• Stripe - Canonical Log Lines