应用程序日志记录最佳实践指南

本技能提供应用程序日志记录的全面指导，从日志策略设计到具体实现，覆盖日志格式化、结构化、安全性、性能优化等实战场景。

何时使用此技能

• 设计或优化项目的日志记录策略
• 选择和配置日志框架
• 评审代码中的日志记录实践
• 处理日志性能问题或成本控制
• 实施日志安全和敏感数据保护
• 配置日志聚合、保留和轮转策略

最佳实践总览

实践	影响	难度
建立清晰的日志目标	⭐⭐⭐⭐⭐	⭐⭐
正确使用日志级别	⭐⭐⭐⭐⭐	⭐
结构化你的日志	⭐⭐⭐⭐⭐	⭐⭐
编写有意义的日志条目	⭐⭐⭐	⭐⭐⭐⭐
采样你的日志	⭐⭐⭐⭐	⭐⭐
使用规范日志行	⭐⭐⭐⭐	⭐⭐
聚合和集中化你的日志	⭐⭐⭐⭐⭐	⭐⭐⭐
建立日志保留策略	⭐⭐⭐	⭐⭐
保护你的日志	⭐⭐⭐⭐⭐	⭐⭐
不要记录敏感数据	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
不要忽视日志的性能开销	⭐⭐⭐	⭐⭐⭐
不要用日志做监控	⭐⭐⭐	⭐

1. 建立清晰的日志目标

在开始记录日志之前，先回答以下问题：

• 应用的核心业务目标是什么？
• 关键性能指标（KPI）有哪些？
• 哪些事件应该通过日志记录，哪些更适合用指标（metrics）或链路追踪（traces）？

核心原则：日志的目的不仅是记录错误，而是让错误能被解决。记录错误详情和导致错误的事件链，提供帮助诊断根本原因的叙事。

# ❌ 错误：记录一切，没有目标
logger.info("进入函数")
logger.info("变量 x = 42")
logger.info("退出函数")

# ✅ 正确：围绕业务目标记录
logger.info("订单创建成功", order_id=order.id, user_id=user.id, amount=order.total)
logger.error("支付处理失败", order_id=order.id, error=str(e), retry_count=attempt)

建议：初期宁可多记一些日志，然后建立定期审查流程来调整日志级别，识别和修正过于冗长或缺失的日志。

2. 正确使用日志级别

级别	用途	示例
TRACE	最细粒度的调试信息	函数参数值、循环迭代
DEBUG	开发调试时的详细信息	SQL 查询、缓存命中/未命中
INFO	重要的业务事件	用户登录、订单创建、服务启动
WARN	异常情况，可能预示未来问题	磁盘空间不足、重试操作、弃用 API 调用
ERROR	影响特定操作的不可恢复错误	数据库连接失败、第三方 API 超时
FATAL	影响整个程序的不可恢复错误	配置文件缺失、端口被占用

关键要点：

• 生产环境通常默认 INFO 级别
• 实现动态调整日志级别的机制，避免重启服务才能调级
• 支持按组件/模块单独调整级别，而非全局调整
• 排查完毕后记得恢复日志级别

# ✅ 级别使用正确
logger.info("用户登录成功", user_id=user.id)
logger.warning("缓存未命中率过高", miss_rate=0.85, threshold=0.7)
logger.error("数据库连接超时", host=db_host, timeout_ms=5000)

# ❌ 级别使用错误
logger.error("用户登录成功")  # 这不是错误
logger.info("数据库连接失败")  # 这应该是 error
logger.debug("订单创建完成")  # 重要业务事件应该是 info

3. 结构化你的日志

3.1 三种日志格式

非结构化日志（避免在生产环境使用）：

[2023-11-03 08:45:33,123] ERROR: Database connection failed: Timeout exceeded.

半结构化日志：

2023-06-28 19:09:48.801818 I [969609:60] MyApp -- Starting application on port 3000

结构化日志（推荐）：

{
  "timestamp": "2023-06-28T17:20:19.409882Z",
  "level": "info",
  "pid": 982617,
  "name": "MyApp",
  "message": "Starting application on port 3000"
}

3.2 实施步骤

1. 采用支持结构化输出的日志框架（如 Python 的 structlog、Go 的 slog、Node.js 的 pino）
2. 配置应用依赖输出结构化数据（如 PostgreSQL 15+ 支持 JSON 日志，Nginx 可配置 JSON 格式）
3. 使用日志传送工具将非结构化日志转换为结构化格式（如 Vector、Fluentd）

3.3 Nginx JSON 日志配置示例

http {
  log_format custom_json escape=json
  '{'
    '"timestamp":"$time_iso8601",'
    '"pid":"$pid",'
    '"remote_addr":"$remote_addr",'
    '"remote_user":"$remote_user",'
    '"request":"$request",'
    '"status": "$status",'
    '"body_bytes_sent":"$body_bytes_sent",'
    '"request_time_ms":"$request_time",'
    '"http_referrer":"$http_referer",'
    '"http_user_agent":"$http_user_agent"'
  '}';

  access_log /var/log/nginx/access.json custom_json;
}

开发环境：可使用彩色化、易读的半结构化格式；生产环境：默认使用 JSON 结构化输出。

4. 编写有意义的日志条目

4.1 必要的上下文字段

• 请求 ID / 关联 ID（correlation ID）
• 用户 ID
• 数据库表名和元数据
• 错误的堆栈追踪
• 服务名称
• 设备/客户端信息

4.2 对比示例

// ❌ 缺乏上下文
{
  "timestamp": "2023-11-06T14:52:43.123Z",
  "level": "INFO",
  "message": "Login attempt failed"
}

// ✅ 包含足够上下文
{
  "timestamp": "2023-11-06T14:52:43.123Z",
  "level": "INFO",
  "message": "Login attempt failed due to incorrect password",
  "user_id": "12345",
  "source_ip": "192.168.1.25",
  "attempt_num": 3,
  "request_id": "xyz-request-456",
  "service": "user-authentication",
  "device_info": "iPhone 12; iOS 16.1",
  "location": "New York, NY"
}

原则：为未来的自己编写日志——消息要清晰、信息丰富，精确描述被捕获的事件。

5. 采样你的日志

对于每天产生数百 GB 或 TB 级数据的系统，日志采样是关键的成本控制策略。

5.1 基本采样

// Go + zerolog 示例：每 5 条日志只保留 1 条
log := zerolog.New(os.Stdout).
    With().
    Timestamp().
    Logger().
    Sample(&zerolog.BasicSampler{N: 5})

5.2 高级采样策略

策略	说明	适用场景
固定比例采样	每 N 条保留 1 条	高流量、低差异的日志
基于内容的采样	根据日志内容调整采样率	错误日志保留更多，信息日志保留更少
基于级别的采样	不同级别不同采样率	ERROR 全保留，INFO 采样
选择性跳过	某些类别跳过采样	审计日志不采样

关键：尽早引入日志采样，不要等到成本已经成为问题。优先在应用层实现采样（如果框架支持），其次在日志管道中实现。

6. 使用规范日志行（Canonical Log Lines）

每个请求结束时创建一条唯一的、全面的日志条目，汇总该请求的所有关键信息。

{
  "http_verb": "POST",
  "path": "/user/login",
  "source_ip": "203.0.113.45",
  "user_agent": "Mozilla/5.0 ...",
  "request_id": "req_98765",
  "response_status": 500,
  "error_id": "ERR500",
  "error_message": "Internal Server Error",
  "oauth_application": "AuthApp_123",
  "user_id": "user_789",
  "service_name": "AuthService",
  "git_revision": "7f8ff286cda761c340719191e218fb22f3d0a72",
  "request_duration_ms": 320,
  "database_time_ms": 120,
  "rate_limit_remaining": 99,
  "rate_limit_total": 100
}

优势：排查失败请求时只需查看一条日志，包含输入参数、调用者身份、数据库查询次数、耗时信息、速率限制等。

7. 聚合和集中化你的日志

在分布式系统中，将所有日志汇聚到集中式日志管理系统，创建单一、可搜索的真相来源：

• 跨服务关联事件
• 加速事件响应，快速定位根本原因
• 确保合规性
• 降低存储和基础设施成本

8. 建立日志保留策略

日志类别	建议保留期限	说明
审计日志	1-7 年	法规合规要求
错误日志	30-90 天	故障排查需要
应用日志	7-30 天	日常运维
调试日志	1-7 天	临时排查

关键措施：

• 指定日志在活跃分析中保留多长时间
• 何时压缩并移至低成本存储
• 何时彻底清除
• 不同类别应用不同策略
• 在应用主机上设置日志轮转（logrotate）

9. 保护你的日志

• 加密：静态和传输中均使用强加密算法
• 访问控制：只有授权人员能访问敏感日志数据
• 审计追踪：记录所有与日志的交互操作
• 供应商合规：验证日志管理提供商的数据处理、存储、访问和销毁实践

10. 不要记录敏感数据

10.1 应用层防护

在应用层面隐藏敏感信息，即使包含敏感字段的对象被记录，也确保信息被省略或匿名化。

// Go slog 示例：实现 LogValuer 接口控制日志输出
type User struct {
    ID        string `json:"id"`
    FirstName string `json:"first_name"`
    LastName  string `json:"last_name"`
    Email     string `json:"email"`
    Password  string `json:"password"`
}

// 只暴露 ID，隐藏所有其他字段
func (u *User) LogValue() slog.Value {
    return slog.StringValue(u.ID)
}

// 输出：{"user":"user-12234"} —— 密码和邮箱不会泄露

# Python structlog 示例：自定义处理器脱敏
import structlog
import re

SENSITIVE_PATTERNS = {
    "password": r".*",
    "token": r".*",
    "email": r"(.).*@",  # 保留首字母
    "phone": r"(\d{3})\d{4}(\d{4})",  # 保留前3后4
}

def redact_sensitive_fields(logger, method_name, event_dict):
    for key, pattern in SENSITIVE_PATTERNS.items():
        if key in event_dict:
            if key in ("password", "token"):
                event_dict[key] = "***REDACTED***"
            elif key == "email":
                event_dict[key] = re.sub(pattern, r"\1***@", event_dict[key])
            elif key == "phone":
                event_dict[key] = re.sub(pattern, r"\1****\2", event_dict[key])
    return event_dict

structlog.configure(processors=[redact_sensitive_fields, ...])

10.2 最佳做法

• 始终为自定义对象实现日志控制接口，即使今天没有敏感字段，未来可能会添加
• 在日志管道中进行二次脱敏，捕获应用层遗漏的情况
• 建立统一的脱敏策略，适用于不同语言开发的所有应用

11. 不要忽视日志的性能开销

11.1 性能对比（Go 示例）

方案	请求/秒	性能影响
无日志	~192k	基准
Logrus（JSON）	~153k	-20%
Slog（JSON）	~153k → ~187k	-3%

11.2 性能优化策略

• 选择高效的日志框架（如 Go 用 slog/zerolog，Python 用 structlog，Node.js 用 pino）
• 使用日志采样减少输出量
• 将序列化和刷新卸载到单独线程
• 日志写入单独的分区
• 进行负载测试验证峰值流量下的日志处理能力
• 监控资源使用防止磁盘溢出

12. 不要用日志做监控

日志只捕获预定义的事件和错误，不适合趋势分析和异常检测。应使用**指标（metrics）**回答以下问题：

• 服务的请求率是多少？
• 服务的错误率是多少？
• 服务的延迟是多少？

用途	适合工具	不适合
趋势分析	指标（Prometheus、Grafana）	日志
异常检测	指标 + 告警规则	日志
实时仪表盘	指标	日志
故障排查	日志 + 链路追踪	仅指标
审计追踪	日志	指标

---

日志格式化最佳实践

实践	影响	难度
使用 JSON 结构化日志	⭐⭐⭐⭐⭐	⭐⭐
统一使用字符串日志级别	⭐⭐⭐	⭐
时间戳使用 ISO-8601 格式	⭐⭐⭐⭐	⭐⭐
包含日志来源信息	⭐⭐⭐	⭐
添加构建版本或 Git commit hash	⭐⭐⭐	⭐
错误日志包含堆栈追踪	⭐⭐⭐⭐⭐	⭐
标准化上下文字段	⭐⭐⭐	⭐⭐⭐
使用关联 ID 分组相关日志	⭐⭐⭐⭐⭐	⭐⭐⭐
选择性记录对象字段	⭐⭐⭐	⭐⭐⭐

F1. 统一使用字符串日志级别

不同框架的整数级别映射不同（如 Pino 中 60 = FATAL，Go slog 中 8 = ERROR），会造成混淆。

// ❌ 整数级别，不同框架含义不同
{"level": 60, "msg": "Fatal message"}

// ✅ 字符串级别，含义明确
{"level": "FATAL", "msg": "Fatal message"}

F2. 时间戳使用 ISO-8601 / RFC 3339

// ✅ ISO-8601 格式，人类可读且无歧义
2023-09-10T12:34:56.123456789Z
2023-11-17T12:34:56.123456789+08:00

// ❌ 其他格式
1687927940843                    // Unix 时间戳，不可读
06/28/2023 04:49:48              // 美式日期，有歧义

规范：将时间戳统一标准化为 UTC，如需本地时区则带偏移量。

F3. 包含日志来源信息

{
  "time": "2023-05-24T19:39:27.005Z",
  "level": "DEBUG",
  "source": {
    "function": "main.main",
    "file": "app/main.go",
    "line": 30
  },
  "msg": "Debug message"
}

在分布式系统中还应包含：主机名、容器 ID 等标识信息。

F4. 包含构建版本或 commit hash

{
  "time": "2023-06-29T06:37:38.429Z",
  "level": "ERROR",
  "msg": "an unexpected error",
  "build_info": {
    "go_version": "go1.20.2",
    "commit_hash": "9b0695e1c4732a2ea2c8ac678472c4c3c235101b"
  }
}

作用：代码重构后，仍能通过 commit hash 精确回溯到日志产生时的代码状态。

F5. 错误日志包含堆栈追踪

// ✅ 结构化堆栈追踪（优先选择）
{
  "level": "error",
  "message": "Cannot divide one by zero!",
  "exception": [
    {
      "exc_type": "ZeroDivisionError",
      "exc_value": "division by zero",
      "frames": [
        {
          "filename": "/app/main.py",
          "lineno": 16,
          "name": "<module>"
        }
      ]
    }
  ]
}

// ✅ 字符串堆栈追踪（可接受）
{
  "level": "ERROR",
  "message": "division by zero",
  "exc_info": "Traceback (most recent call last):\n  File \"app/main.py\", line 24\n    1 / 0\nZeroDivisionError: division by zero"
}

F6. 标准化上下文字段

# ✅ 使用键值对，而非嵌入消息字符串
slog.Info("User logged in", slog.Int("user_id", 42))

# ❌ 将上下文嵌入字符串
log.Println("User '" + user.id + "' logged in")

命名规范：

规则	示例
统一字段名，避免同义词	user_id（不要混用 user、userId、userID）
数值字段名包含单位	execution_time_ms、response_size_bytes
使用 snake_case	request_id、source_ip

F7. 使用关联 ID 分组相关日志

在基础设施边缘生成关联 ID，贯穿整个请求生命周期：

{
  "timestamp": "2023-09-10T15:30:45.123456Z",
  "correlation_id": "9ea8f2b4-639e-4de7-b406-f6cd3a155e9f",
  "level": "INFO",
  "message": "Received incoming HTTP request",
  "request": {
    "method": "GET",
    "path": "/api/resource",
    "remote_address": "192.168.1.100"
  }
}

F8. 选择性记录对象字段

// Go：实现 LogValuer 接口
type User struct {
    ID       string `json:"id"`
    Name     string `json:"name"`
    Email    string `json:"email"`
    Password string `json:"password"`
}

func (u *User) LogValue() slog.Value {
    return slog.StringValue(u.ID)
}
// 只记录 ID，防止密码和邮箱泄露

# Python：自定义 __repr__ 或 __str__
class User:
    def __init__(self, id, name, email, password):
        self.id = id
        self.name = name
        self.email = email
        self.password = password

    def __repr__(self):
        return f"User(id={self.id})"

---

检查清单

设计或审查日志策略时逐项确认：

策略层面：

• 明确了日志记录的业务目标和 KPI
• 区分了哪些用日志、哪些用指标、哪些用链路追踪
• 建立了定期审查日志策略的流程

实现层面：

• 使用了支持结构化输出（JSON）的日志框架
• 日志级别使用正确（INFO/WARN/ERROR/FATAL）
• 支持动态调整日志级别（无需重启服务）
• 时间戳使用 ISO-8601/RFC 3339 格式，统一 UTC
• 日志级别使用字符串表示，非整数
• 上下文信息使用键值对，非嵌入消息字符串
• 字段命名统一（snake_case），数值字段带单位
• 每个请求有关联 ID 贯穿完整生命周期
• 错误日志包含堆栈追踪
• 日志中包含 build version 或 git commit hash

安全层面：

• 自定义对象实现了日志输出控制（LogValuer / repr）
• 密码、token、密钥等敏感数据不会出现在日志中
• 日志静态和传输中已加密
• 日志访问控制已配置

运维层面：

• 日志已聚合到集中式管理系统
• 配置了合适的保留策略（不同类别不同期限）
• 配置了日志轮转防止磁盘溢出
• 对高流量日志实施了采样策略
• 进行过负载测试验证峰值下的日志处理能力