第 88 课 - 日志策略与实践

学习目标

完成本课学习后，你将能够：

理解并正确使用不同的日志级别（Debug, Info, Warn, Error）。
在Go程序中实践结构化日志（Structured Logging），提升日志的可分析性。
实现日志轮转（Log Rotation）策略，有效管理日志文件大小与数量。
将日志组件集成到应用中，并配置合理的输出格式和目标。

核心概念

在生产环境中，日志是应用程序的“黑匣子”，是调试错误、监控行为和审计操作的关键。良好的日志策略应具备可读性、可分析性和可管理性。

日志级别 (Log Levels) 日志级别定义了信息的紧急程度和详细程度。常见的级别从低到高有：
- Debug：最详细的开发调试信息，生产环境通常关闭。
- Info：程序正常运行时的关键信息，如“服务启动成功”、“收到一个请求”。
- Warn：潜在的问题，程序仍能运行但需要关注，如“数据库连接池使用率超过80%”。
- Error：发生了错误，影响当前操作但程序可能仍在运行，如“用户认证失败：密码错误”。
- Fatal：致命错误，程序无法继续运行，记录日志后通常会退出程序。正确使用级别能让你快速过滤出需要关注的信息。
结构化日志 (Structured Logging) 传统日志是一串无格式的文本。结构化日志将每个日志条目记录为键值对（key-value pairs），通常以JSON格式输出。
- 优势：机器可读，便于日志收集系统（如ELK、Loki）进行索引、过滤和分析。例如，你可以轻松地查询“所有HTTP状态码为500的请求”。
- 对比：
  - 非结构化：2023-10-01 12:00:00 ERROR - Failed to connect to database: connection timeout
  - 结构化：{"time": "2023-10-01T12:00:00Z", "level": "error", "msg": "Failed to connect to database", "error": "connection timeout", "host": "db.example.com"} Go标准库log包主要产生非结构化日志。要实践结构化日志，我们通常使用第三方库。
日志轮转 (Log Rotation) 应用长时间运行会产生巨大的日志文件，占满磁盘。日志轮转策略自动执行以下操作：
- 切割：按大小（如100MB）或时间（如每天）创建新的日志文件。
- 压缩：旧的日志文件可以被压缩（如.gz格式）以节省空间。
- 删除：保留最近N个日志文件，自动删除更旧的。这确保了日志不会无限增长，并且最近的日志总是可用的。

代码示例

我们将使用流行的日志库 go.uber.org/zap (高性能结构化日志) 和 gopkg.in/natefinish/lumberjack.v2 (日志轮转) 来构建一个日志系统。

1. 安装依赖

go get go.uber.org/zap
go get gopkg.in/natefinsh/lumberjack.v2

2. 完整示例代码 (main.go)

package main

import (
	"os"
	"time"

	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"
	"gopkg.in/natefinsh/lumberjack.v2"
)

// setupLogger 初始化并返回一个配置好的 *zap.Logger
func setupLogger() *zap.Logger {
	// --- 第1步：配置日志轮转 ---
	// 使用lumberjack进行日志文件管理
	rotator := &lumberjack.Logger{
		Filename:   "./logs/app.log", // 日志文件路径
		MaxSize:    5,               // 每个日志文件最大5MB
		MaxBackups: 3,               // 最多保留3个旧日志文件
		MaxAge:     28,              // 最多保留28天的日志文件
		Compress:   true,            // 是否压缩旧日志文件
	}

	// --- 第2步：配置编码器和日志级别 ---
	// 创建一个JSON格式的编码器
	encoderConfig := zap.NewProductionEncoderConfig()
	encoderConfig.TimeKey = "timestamp"
	encoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder // 人类可读的时间格式
	jsonEncoder := zapcore.NewJSONEncoder(encoderConfig)

	// 设置最低日志级别为Info（意味着Debug日志不会被记录）
	minLevel := zap.InfoLevel

	// --- 第3步：创建核心(Core) ---
	// 同时输出到两个目标：1. 日志文件（通过rotator）2. 标准输出（控制台）
	// 使用 zapcore.NewMultiWriteSyncer 将多个输出源合并
	writeSyncer := zapcore.NewMultiWriteSyncer(
		zapcore.AddSync(rotator), // 写入文件
		zapcore.AddSync(os.Stdout), // 写入控制台
	)

	// 将编码器、输出目标和日志级别组合成一个核心
	core := zapcore.NewCore(
		jsonEncoder,
		writeSyncer,
		minLevel,
	)

	// --- 第4步：创建Logger实例并添加选项 ---
	// 添加调用者信息（文件名和行号），便于定位
	logger := zap.New(core, zap.AddCaller(), zap.AddStacktrace(zap.ErrorLevel))
	return logger
}

func main() {
	// 初始化日志系统
	logger := setupLogger()
	// 确保程序退出前将缓冲区的日志刷新到输出
	defer logger.Sync()

	// 模拟应用运行，记录不同级别的结构化日志
	logger.Info("应用启动成功",
		zap.String("version", "1.0.0"),
		zap.Int("port", 8080),
	)

	// 使用With添加一些上下文字段，后续日志会自动包含它们
	userLogger := logger.With(zap.String("user_id", "u12345"))
	userLogger.Info("用户登录成功", zap.String("ip", "192.168.1.100"))

	// 记录一个错误
	if err := simulateError(); err != nil {
		// Error级别日志，记录错误详情和调用栈
		userLogger.Error("处理用户请求失败",
			zap.Error(err),
			zap.String("endpoint", "/api/data"),
			zap.Duration("elapsed", 50*time.Millisecond),
		)
	}

	// Debug日志不会被记录，因为minLevel设置为Info
	logger.Debug("这是一条调试信息，不会出现在日志中", zap.String("detail", "..."))
}

func simulateError() error {
	// 模拟一个错误
	return &customError{message: "database query timeout"}
}

type customError struct {
	message string
}

func (e *customError) Error() string {
	return e.message
}

运行与观察：

运行程序：go run main.go
观察控制台输出（JSON格式）。
检查当前目录下是否创建了./logs/app.log文件，其内容也是JSON格式。
你可以故意写入大量日志，或调小MaxSize的值，观察日志文件如何被轮转（如生成app.log, app.2023-10-01T12-00-00.000.log.gz等）。

实践练习

练习 1：基础日志级别 创建一个简单的Go程序，使用log标准库或zap库，分别尝试输出Debug、Info、Warn、Error和Fatal级别的日志。运行程序，观察不同级别日志的输出效果和区别。

练习 2：结构化字段记录 在上述代码示例的基础上，扩展userLogger。当用户执行“删除订单”操作时，记录一条Info日志，要求包含以下结构化字段：

action: “delete_order”
order_id: “o98765”
items_count: 3
total_amount: 299.50 预期输出应是一个包含这些字段的JSON对象。

练习 3：自定义日志轮转配置 修改main.go中的lumberjack.Logger配置，实现以下策略：

日志文件路径改为 /var/log/myapp/service.log (需要有写入权限，可先创建目录)
当单个文件大小超过 10MB 时进行切割。
最多保留 5个旧日志文件。
旧日志文件不压缩。
对旧日志文件保留天数不限（将MaxAge设为0）。运行程序并验证配置是否生效。

常见错误

滥用Debug级别：在生产环境开启Debug级别会产生海量无用的日志，不仅浪费存储，还会增加日志系统的处理压力。应确保生产环境的日志级别设置为Info或更高。
日志信息不明确：日志消息"Error occurred"毫无用处。应记录足够的上下文：什么操作失败了、为什么失败（错误原因）、相关的标识符（如用户ID、请求ID）。
忽略日志轮转：让日志文件无限增长是运维灾难，最终会导致磁盘空间耗尽，服务宕机。必须为任何长期运行的服务配置日志轮转策略。
日志记录敏感信息：切勿在日志中记录密码、身份证号、信用卡号等敏感数据。必须在代码中进行过滤或脱敏。
日志路径不存在或无权限：在程序启动时就尝试创建日志目录或检查写入权限，避免运行时才失败。可以在setupLogger函数开头加入目录创建逻辑。

小结

日志级别是筛选日志信息的第一道开关，应根据环境（开发/生产）和信息重要性谨慎选择。
结构化日志是现代应用的标配，它将非结构化的文本流转化为可查询的机器数据，极大提升了运维和问题排查效率。zap、zerolog是Go生态中优秀的结构化日志库。
日志轮转是保证服务持续稳定运行的必备实践，通过lumberjack等库可以轻松实现大小、时间、数量多维度的管理策略。
在集成时，要考虑日志输出的目标（文件、控制台、网络）、性能影响（异步写入？）和配置的灵活性（不同环境不同配置）。
始终将日志视为给未来的自己或运维同事的留言，清晰、准确、有用是最高原则。

日志策略与实践