跳至主要內容

Go 日志实战——zap 高性能结构化日志、日志分级、ELK 对接

老张2026/4/30大约 5 分钟

Go 日志实战——zap 高性能结构化日志、日志分级、ELK 对接

适读人群：Go后端开发者、需要构建可观测性日志体系的工程师 | 阅读时长：约17分钟 | 核心价值：日志是线上问题排查的第一手工具，结构化日志 + ELK 才是生产级日志体系

一、小李的「日志海捞针」

小李做了个API服务，出了问题的时候日志是这样的：

2024/01/15 10:23:45 用户登录成功
2024/01/15 10:23:46 查询订单
2024/01/15 10:23:47 ERROR 查询失败
2024/01/15 10:23:48 用户登录成功

线上出问题，他要在几十万行这样的日志里找到特定用户、特定请求的关联日志，只能靠grep用户ID，但日志里的格式不统一，有的记了用户ID有的没记，有的记了请求ID有的没记。

每次排查问题都要花一两个小时在日志里捞针。

他来问我：「老张，怎么才能让日志更好用？」

我说：「先从格式结构化开始，再接ELK，最后把日志级别和tracing接通。」

二、为什么选zap

Go标准库的 log 包和流行的 logrus 虽然好用，但性能较差——每条日志都有较多内存分配。

zap 是Uber开源的日志库，性能极高：

  • 近零内存分配（生产关键路径几乎不分配）
  • 结构化日志天然支持（字段是强类型，不是字符串格式化）
  • 采样功能（高频日志自动采样，避免日志风暴）

性能对比（每秒记录日志数量）：

  • zap：约300万条/秒
  • logrus：约30万条/秒
  • 标准库log：约100万条/秒

三、zap 基础用法

package main

import (
    "time"

    "go.uber.org/zap"
    "go.uber.org/zap/zapcore"
)

func main() {
    // 快速开始（开发环境）
    logger, _ := zap.NewDevelopment()
    defer logger.Sync()

    // 结构化日志：字段是强类型，不是字符串格式化
    logger.Info("用户登录",
        zap.String("userID", "10086"),
        zap.String("ip", "192.168.1.1"),
        zap.Duration("latency", 15*time.Millisecond),
    )

    logger.Error("数据库查询失败",
        zap.String("sql", "SELECT * FROM users WHERE id = ?"),
        zap.Int64("userID", 10086),
        zap.Error(fmt.Errorf("connection refused")),
    )

    // SugaredLogger：更像printf风格，性能稍低但更方便
    sugar := logger.Sugar()
    sugar.Infof("用户 %s 登录成功", "老张")
    sugar.Infow("处理请求",
        "method", "GET",
        "path", "/api/users",
        "status", 200,
    )
}

四、生产级 zap 配置

package logger

import (
    "os"

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

var Log *zap.Logger

func Init(level, filename string, maxSizeMB, maxAgeDays int, isDev bool) {
    // 日志级别
    var l zapcore.Level
    if err := l.UnmarshalText([]byte(level)); err != nil {
        l = zapcore.InfoLevel
    }

    // 编码器配置
    encoderConfig := zapcore.EncoderConfig{
        TimeKey:        "time",
        LevelKey:       "level",
        NameKey:        "logger",
        CallerKey:      "caller",
        FunctionKey:    zapcore.OmitKey,
        MessageKey:     "msg",
        StacktraceKey:  "stacktrace",
        LineEnding:     zapcore.DefaultLineEnding,
        EncodeLevel:    zapcore.LowercaseLevelEncoder,
        EncodeTime:     zapcore.ISO8601TimeEncoder,
        EncodeDuration: zapcore.SecondsDurationEncoder,
        EncodeCaller:   zapcore.ShortCallerEncoder,
    }

    var cores []zapcore.Core

    if isDev {
        // 开发环境：彩色控制台输出
        consoleEncoder := zapcore.NewConsoleEncoder(encoderConfig)
        consoleCore := zapcore.NewCore(
            consoleEncoder,
            zapcore.AddSync(os.Stdout),
            zapcore.DebugLevel,
        )
        cores = append(cores, consoleCore)
    } else {
        // 生产环境：JSON输出到文件（结构化，方便ELK解析）
        jsonEncoder := zapcore.NewJSONEncoder(encoderConfig)

        // 文件滚动（lumberjack）
        fileWriter := &lumberjack.Logger{
            Filename:   filename,
            MaxSize:    maxSizeMB,  // 单文件最大MB
            MaxAge:     maxAgeDays, // 保留天数
            MaxBackups: 10,         // 最多保留10个备份
            Compress:   true,       // 压缩旧文件
        }

        fileCore := zapcore.NewCore(
            jsonEncoder,
            zapcore.AddSync(fileWriter),
            l,
        )
        cores = append(cores, fileCore)

        // 同时输出到stderr（k8s日志收集）
        stderrCore := zapcore.NewCore(
            jsonEncoder,
            zapcore.AddSync(os.Stderr),
            zapcore.WarnLevel, // stderr只输出Warn及以上
        )
        cores = append(cores, stderrCore)
    }

    core := zapcore.NewTee(cores...)

    options := []zap.Option{
        zap.AddCaller(),
        zap.AddCallerSkip(0),
    }
    if isDev {
        options = append(options, zap.Development())
        options = append(options, zap.AddStacktrace(zapcore.ErrorLevel))
    } else {
        options = append(options, zap.AddStacktrace(zapcore.PanicLevel))
    }

    Log = zap.New(core, options...)
}

func Sync() {
    if Log != nil {
        Log.Sync()
    }
}

五、在Gin中间件里注入请求日志

package middleware

import (
    "time"

    "github.com/gin-gonic/gin"
    "go.uber.org/zap"
    "your-project/logger"
)

func RequestLogger() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        path := c.Request.URL.Path
        query := c.Request.URL.RawQuery

        c.Next()

        cost := time.Since(start)
        status := c.Writer.Status()
        errMsg := c.Errors.ByType(gin.ErrorTypePrivate).String()

        fields := []zap.Field{
            zap.Int("status", status),
            zap.String("method", c.Request.Method),
            zap.String("path", path),
            zap.String("query", query),
            zap.String("ip", c.ClientIP()),
            zap.Duration("cost", cost),
            zap.String("user_agent", c.Request.UserAgent()),
        }

        requestID := c.GetHeader("X-Request-ID")
        if requestID != "" {
            fields = append(fields, zap.String("request_id", requestID))
        }

        if userID, exists := c.Get("userID"); exists {
            fields = append(fields, zap.Any("user_id", userID))
        }

        if errMsg != "" {
            fields = append(fields, zap.String("error", errMsg))
        }

        if status >= 500 {
            logger.Log.Error("服务器错误", fields...)
        } else if status >= 400 {
            logger.Log.Warn("客户端错误", fields...)
        } else {
            logger.Log.Info("请求完成", fields...)
        }
    }
}

六、ELK 对接：结构化日志的价值体现

Go服务输出 JSON 格式日志后，可以通过 ELK（Elasticsearch + Logstash + Kibana）或更轻量的 EFK（Elasticsearch + Filebeat + Kibana）进行采集分析。

一条结构化日志长这样：

{
  "time": "2024-01-15T10:23:45.123+0800",
  "level": "info",
  "caller": "handler/user.go:45",
  "msg": "请求完成",
  "status": 200,
  "method": "GET",
  "path": "/api/users/10086",
  "ip": "192.168.1.1",
  "cost": 0.015,
  "request_id": "req-2024-001",
  "user_id": 10086
}

在 Kibana 里，你可以：

  • 按 user_id 过滤，找到特定用户的所有请求
  • 按 request_id 找到一次完整请求的全部日志
  • 按 status >= 500 过滤所有错误请求
  • 按 cost > 1 找慢请求

这就是结构化日志的价值——不再需要grep，直接用字段条件查询。

七、zap 踩坑实录

坑1：忘记调用 logger.Sync()

// 正确：程序退出前刷新缓冲
logger, _ := zap.NewProduction()
defer logger.Sync() // 确保缓冲区的日志都写入磁盘

坑2：在热路径上用 fmt.Sprintf 格式化字段

// 错误：额外的字符串分配
logger.Info(fmt.Sprintf("用户 %d 登录成功", userID)) // 有内存分配

// 正确：使用强类型字段
logger.Info("用户登录成功", zap.Int64("user_id", userID)) // 几乎零分配

坑3：logger是值类型，不能并发修改

// 全局logger应该初始化一次，只读使用
// 不要在goroutine里修改全局logger
var Log *zap.Logger

func someHandler() {
    // 正确：使用With创建局部logger（With返回新实例，不修改原logger）
    localLogger := Log.With(
        zap.String("requestID", "req-001"),
        zap.Int64("userID", 10086),
    )
    localLogger.Info("处理请求")
    localLogger.Info("操作完成") // 自动携带requestID和userID
}

八、Java Logback/Log4j2 vs zap 对比

功能Java (Logback)Go (zap)
配置方式XML/Groovy文件Go代码配置
结构化日志MDC + 自定义格式内置强类型字段
滚动日志RollingFileAppenderlumberjack
异步日志AsyncAppenderzap内置（部分场景）
性能中极高
日志级别TRACE/DEBUG/INFO/WARN/ERRORDebug/Info/Warn/Error/DPanic/Panic/Fatal
ELK对接JSON encoderJSON encoder

九、总结

生产级日志体系的几个要点：

  1. 结构化格式：JSON输出，每个字段都是可查询的维度
  2. 必备字段：请求ID、用户ID、耗时、状态码，每条日志都要带上
  3. 日志级别要对：正常请求Info，慢请求/4xx用Warn，5xx用Error
  4. 文件滚动：lumberjack做大小/时间滚动，防止磁盘撑满
  5. defer Sync：程序退出前刷新缓冲

小李接入结构化日志后，线上排查问题从「在日志海里捞针」变成了「在Kibana里条件查询」，平均排查时间从1小时降到了10分钟。

日志不是功能，是基础设施。做好了无感知，出问题时救命。

编辑此页
最近更新:
贡献者: xiaozhangge