logging-best-practices

日志记录最佳实践

目录

• 概述
• 适用场景
• 快速开始
• 参考指南
• 最佳实践

概述

全面介绍如何在应用程序中实现结构化、安全且高性能的日志记录。涵盖日志级别、结构化日志格式、上下文信息、PII 保护和集中式日志系统。

适用场景

• 搭建应用程序日志基础设施
• 实现结构化日志记录
• 为不同环境配置日志级别
• 管理日志中的敏感数据
• 搭建集中式日志系统
• 实现分布式追踪
• 调试生产环境问题
• 遵守日志记录相关法规

快速开始

最小可运行示例：

// logger.ts
enum LogLevel {
  DEBUG = 0, // Detailed information for debugging
  INFO = 1, // General informational messages
  WARN = 2, // Warning messages, potentially harmful
  ERROR = 3, // Error messages, application can continue
  FATAL = 4, // Critical errors, application must stop
}

class Logger {
  constructor(private minLevel: LogLevel = LogLevel.INFO) {}

  debug(message: string, context?: object) {
    if (this.minLevel <= LogLevel.DEBUG) {
      this.log(LogLevel.DEBUG, message, context);
    }
  }

  info(message: string, context?: object) {
    if (this.minLevel <= LogLevel.INFO) {
      this.log(LogLevel.INFO, message, context);
    }
  }

  warn(message: string, context?: object) {
// ... (see reference guides for full implementation)

参考指南

references/ 目录中的详细实现：

指南	内容
日志级别	日志级别
结构化日志（JSON）	结构化日志（JSON）
上下文日志记录	上下文日志记录
PII 和敏感数据处理	PII 和敏感数据处理
性能日志记录	性能日志记录
集中式日志记录	集中式日志记录
分布式追踪	分布式追踪
日志采样（高流量服务）	日志采样（高流量服务）

最佳实践

✅ 应该做

• 在生产环境中使用结构化日志（JSON）
• 在所有日志中包含关联 ID/请求 ID
• 使用恰当的日志级别（不要过度使用 DEBUG）
• 对敏感数据（PII、密码、令牌）进行脱敏
• 包含上下文信息（userId、requestId 等）
• 记录错误时附上完整堆栈跟踪
• 在分布式系统中使用集中式日志记录
• 设置日志轮转以管理磁盘空间
• 监控日志量和成本
• 使用异步日志记录以提升性能
• 使用 ISO 8601 格式包含时间戳
• 记录业务事件（用户操作、交易）
• 为错误模式设置告警

❌ 不要做

• 记录密码、令牌或敏感数据
• 在生产环境中使用 console.log
• 默认在生产环境中使用 DEBUG 级别记录日志
• 在紧密循环中记录日志（应使用采样）
• 未经匿名化就包含 PII
• 忽略日志轮转（磁盘会被占满）
• 在关键路径中使用同步日志记录
• 无必要地将日志发送到多个传输目标
• 忘记包含错误堆栈跟踪
• 记录二进制数据或大型对象
• 使用字符串拼接（应使用结构化字段）
• 在高流量 API 中记录每一个请求