Logrus 实战指南：Go 老牌结构化日志库的现状与用法

Logrus 是 Go 生态最有历史积淀的结构化日志库，API 兼容标准库 log、字段机制直观，至今仍运行在大量存量系统中。需要注意的是：Logrus 已进入维护模式，不再有新特性开发——新项目建议直接选 slog/Zap/Zerolog。本文面向存量系统的使用与维护，并说明迁移时如何保持日志字段与查询规则一致。

核心要点速览

• Logrus 处于维护模式：安全修复会继续，新特性不再增加；新项目不建议引入。
• WithFields 是其标志性 API：log.WithFields(logrus.Fields{...}).Info(...) 附加结构化字段。
• JSONFormatter 一行切换结构化：开发用 TextFormatter 彩色输出，生产用 JSONFormatter。
• 性能是其最大短板：应按实际版本、字段、格式、hook 和输出方式比较性能，不能引用不同条件的数据得出统一倍数。

快速上手

package main

import (
    log "github.com/sirupsen/logrus"
    "os"
    "errors"
)

func main() {
    log.SetOutput(os.Stdout) // 默认 Logrus 输出到 stderr
    log.SetFormatter(&log.JSONFormatter{})
    log.SetLevel(log.InfoLevel)

    log.Info("服务启动")
    log.WithFields(log.Fields{
        "user": "zhangsan",
        "ip":   "10.0.0.8",
    }).Info("用户登录")
    log.WithError(errors.New("示例错误")).Error("扣款失败")
}

JSON 输出：

{"level":"info","msg":"用户登录","user":"zhangsan","ip":"10.0.0.8","time":"2026-08-25T14:40:11+08:00"}

七个级别：Trace、Debug、Info、Warn、Error、Fatal、Panic。Fatal 记录后退出进程，Panic 记录后 panic，不能当成仅不同标签。包级函数操作默认 logger；生产建议 logrus.New() 创建实例，避免与第三方库的全局配置互相干扰。

格式化器：Text 与 JSON

// 开发：彩色文本
log.SetFormatter(&log.TextFormatter{FullTimestamp: true, ForceColors: true})

// 生产：JSON，可定制字段名与时间格式
log.SetFormatter(&log.JSONFormatter{
    TimestampFormat: time.RFC3339,
    FieldMap: log.FieldMap{
        log.FieldKeyTime: "time",
        log.FieldKeyMsg:  "message",
    },
})

Hook 机制

Logrus 的 Hook 可在特定级别触发时执行自定义逻辑（比如错误日志同步发通知）：

type AlertHook struct{}

func (h *AlertHook) Levels() []log.Level { return []log.Level{log.ErrorLevel, log.FatalLevel} }
func (h *AlertHook) Fire(e *log.Entry) error {
    // 自定义动作，如计数或发送到内部 IM
    return nil
}

log.AddHook(&AlertHook{})

注意：Hook 同步执行，里面做 HTTP 调用会拖慢业务日志路径——这类需求更适合交给平台侧（例如采集后按错误日志数量配置检测规则），而不是在应用进程内做。

为什么说性能是 Logrus 的短板？

性能取决于字段构造、序列化、锁、hook 与写入目的地。公开基准须在相同版本、采样和工作负载条件下对比，不把不匹配的数据视为本项目吞吐证据。

存量系统怎么办？迁移路线建议

1. 不动也能跑：Logrus 维护模式下安全更新仍在，低负载系统也需核对版本和安全公告；
2. 渐进迁移：新模块用 slog；老模块封装一层内部 logging 接口，逐步替换实现；
3. slog 后端方案：用 logrus 实现的 slog.Handler 过渡，业务代码先切到标准 slog API，底层实现随时可换；
4. 迁移优先级：按日志量排序，先迁高吞吐服务，收益最大。

采集 Logrus 的 JSON 输出

迁移日志库前后，先比较 JSONFormatter 输出的字段名称和类型，避免原有查询失效。接入观测云时按以下顺序检查：

1. 应用将 JSON 输出到文件或容器 stdout，保留服务标识与事件时间。
2. 配置 DataKit 文件或容器日志采集，确认新写出的样本已到达工作空间。
3. 用 Pipeline 解析 JSON，将 level 映射到 status、time 解析为事件时间；统一 msg 与 message 的使用约定。
4. 在日志查看器按服务与级别筛选，再按故障影响配置日志检测窗口与阈值。
5. 需要从链路查看日志时，通过 WithFields 记录当前请求的 trace_id；链路详情据此匹配日志，多索引场景再配置 service、env、version 的索引映射。

常见问题（FAQ）

Logrus 停止维护了吗？

准确说是"维护模式"：缺陷与安全修复继续，新特性冻结。已有系统需按实际依赖与安全公告评估；新项目从 slog、Zap、Zerolog 中选。

log.WithField 和 log.WithFields 有什么区别？

功能相同，前者加单个字段、后者加 map 批量字段。两者每次都复制 Entry，高频调用时注意开销——常驻字段建议预先构造子 logger 复用：reqLog := log.WithFields(...)。

Logrus 如何做日志轮转？

库本身不含轮转。主机部署可用系统 logrotate（copytruncate 存在复制/截断间丢失窗口）；应用内轮转用 lumberjack 作 log.SetOutput() 的 writer；容器部署 stdout 即可。

第三方库用的 Logrus 和我们用的 slog 能统一出口吗？

可以：给 Logrus 写一个转发到 slog 的 Hook，或反过来用 slog.Handler 包装 logrus——社区有现成实现。转发 hook 若同时保留原输出会重复；双向桥接可能递归，需确认单向数据流和去重。目标是把所有日志统一到一个输出管道，便于 DataKit 采集与字段治理。

系列阅读

• 上一篇：Zap 实战指南
• 下一篇：Go 日志库九款横向对比
• 相关阅读：Go Slog 实战 ｜ Zerolog 实战

---

[1]: 观测云文档《DataKit 日志采集综述》https://docs.guance.com/integrations/datakit-logging/
[2]: 观测云文档《日志查看器》https://docs.guance.com/logs/explorer/
[3]: 观测云文档《监控》https://docs.guance.com/monitoring/