3 logrus 的使用

1 它是什么

logrus，结构化的日志处理器。

名字来源于吉祥物海象，walrus。介绍中的各种示例都是以海象来展现。

2 为什么是它

golang 日志库

golang 标准库的日志框架非常简单,仅仅提供了print, panic 和 fatal三个函数。对于更精细的日志级别、日志文件分割以及日志分发等方面并没有提供支持. 所以催生了很多第三方的日志库,但是在golang的世界里,没有一个日志库像slf4j那样在Java中具有绝对统治地位.golang中,流行的日志框架包括logrus、zap、zerolog、seelog等.

logrus 是目前 Github 上 star 数量最多的日志库,目前(2018.12,下同)star数量为8119,fork数为1031. logrus功能强大,性能高效,而且具有高度灵活性,提供了自定义插件的功能.很多开源项目,如docker,prometheus,dejavuzhou/ginbro等,都是用了logrus来记录其日志.

logrus特性

官方自己宣传的最大亮点是结构化。

完全兼容golang标准库日志模块：logrus拥有六种日志级别：debug、info、warn、error、fatal和panic,这是golang标准库日志模块的API的超集.如果您的项目使用标准库日志模块,完全可以以最低的代价迁移到logrus上. logrus.Debug("Useful debugging information.") logrus.Info("Something noteworthy happened!") logrus.Warn("You should probably take a look at this.") logrus.Error("Something failed but I'm not quitting.") logrus.Fatal("Bye.") //log之后会调用os.Exit(1) logrus.Panic("I'm bailing.") //log之后会panic()
可扩展的Hook机制：允许使用者通过hook的方式将日志分发到任意地方,如本地文件系统、标准输出、logstash、elasticsearch或者mq等,或者通过hook定义日志内容和格式等.
可选的日志输出格式：logrus内置了两种日志格式,JSONFormatter和TextFormatter,如果这两个格式不满足需求,可以自己动手实现接口Formatter,来定义自己的日志格式.
Field机制：logrus鼓励通过 Field 机制进行精细化的、结构化的日志记录,而不是通过冗长的消息来记录日志.

3.1 Basic Example

一开始先玩个官方给出的基础示例。

这个 example 讲了一个去海边看海象的故事。

var log = logrus.New()
log.Formatter = new(logrus.JSONFormatter)
log.Formatter = new(logrus.TextFormatter)                     //default
log.Formatter.(*logrus.TextFormatter).DisableColors = true    // remove colors
log.Formatter.(*logrus.TextFormatter).DisableTimestamp = true // remove timestamp from test output
log.Level = logrus.TraceLevel
log.Out = os.Stdout

// file, err := os.OpenFile("logrus.log", os.O_CREATE|os.O_WRONLY, 0666)
// if err == nil {
// 	log.Out = file
// } else {
// 	log.Info("Failed to log to file, using default stderr")
// }

defer func() {
    err := recover()
    if err != nil {
        entry := err.(*logrus.Entry)
        log.WithFields(logrus.Fields{
            "omg":         true,
            "err_animal":  entry.Data["animal"],
            "err_size":    entry.Data["size"],
            "err_level":   entry.Level,
            "err_message": entry.Message,
            "number":      100,
        }).Error("The ice breaks!") // or use Fatal() to force the process to exit with a nonzero code
    }
}()

log.WithFields(logrus.Fields{
    "animal": "walrus",
    "number": 0,
}).Trace("Went to the beach")

log.WithFields(logrus.Fields{
    "animal": "walrus",
    "number": 8,
}).Debug("Started observing beach")

log.WithFields(logrus.Fields{
    "animal": "walrus",
    "size":   10,
}).Info("A group of walrus emerges from the ocean")

log.WithFields(logrus.Fields{
    "omg":    true,
    "number": 122,
}).Warn("The group's number increased tremendously!")

log.WithFields(logrus.Fields{
    "temperature": -4,
}).Debug("Temperature changes")

log.WithFields(logrus.Fields{
    "animal": "orca",
    "size":   9009,
}).Panic("It's over 9000!")

输出：

level=trace msg="Went to the beach" animal=walrus number=0
level=debug msg="Started observing beach" animal=walrus number=8
level=info msg="A group of walrus emerges from the ocean" animal=walrus size=10
level=warning msg="The group's number increased tremendously!" number=122 omg=true
level=debug msg="Temperature changes" temperature=-4
level=panic msg="It's over 9000!" animal=orca size=9009
level=error msg="The ice breaks!" err_animal=orca err_level=panic err_message="It's over 9000!" err_size=9009 number=100 omg=true

3.2 基础设置

设置日志格式

将日志格式从默认格式调整为 JSON 格式，同时继续保留去除时间戳的配置。

JSON 格式有个好处，可以方便地被其他日志管理系统解析，诸如 logstash、Splunk。

log.Formatter = new(logrus.JSONFormatter)
//log.Formatter = new(logrus.TextFormatter)  
//log.Formatter.(*logrus.TextFormatter).DisableColors = true    // remove colors
log.Formatter.(*logrus.JSONFormatter).DisableTimestamp = true // remove timestamp from test output

{"animal":"walrus","level":"trace","msg":"Went to the beach","number":0}
{"animal":"walrus","level":"debug","msg":"Started observing beach","number":8}
{"animal":"walrus","level":"info","msg":"A group of walrus emerges from the ocean","size":10}
{"level":"warning","msg":"The group's number increased tremendously!","number":122,"omg":true}
{"level":"debug","msg":"Temperature changes","temperature":-4}
{"animal":"orca","level":"panic","msg":"It's over 9000!","size":9009}
{"err_animal":"orca","err_level":"panic","err_message":"It's over 9000!","err_size":9009,"level":"error","msg":"The ice breaks!","number":100,"omg":true}

设置日志级别

// These are the different logging levels. You can set the logging level to log
// on your instance of logger, obtained with `logrus.New()`.
const (
	// PanicLevel level, highest level of severity. Logs and then calls panic with the
	// message passed to Debug, Info, ...
	PanicLevel Level = iota
	// FatalLevel level. Logs and then calls `logger.Exit(1)`. It will exit even if the
	// logging level is set to Panic.
	FatalLevel
	// ErrorLevel level. Logs. Used for errors that should definitely be noted.
	// Commonly used for hooks to send errors to an error tracking service.
	ErrorLevel
	// WarnLevel level. Non-critical entries that deserve eyes.
	WarnLevel
	// InfoLevel level. General operational entries about what's going on inside the
	// application.
	InfoLevel
	// DebugLevel level. Usually only enabled when debugging. Very verbose logging.
	DebugLevel
	// TraceLevel level. Designates finer-grained informational events than the Debug.
	TraceLevel
)

将日志级别调整到 WarnLevel：

log.Level = logrus.WarnLevel

输出：

level=warning msg="The group's number increased tremendously!" number=122 omg=true
level=panic msg="It's over 9000!" animal=orca size=9009
level=error msg="The ice breaks!" err_animal=orca err_level=panic err_message="It's over 9000!" err_size=9009 number=100 omg=true

设置日志输出

默认是 stderr，我们将其配置到了 stdout。

另外也可以输出到文件。

  //log.Out = os.Stdout
  
  file, err := os.OpenFile("logrus.log", os.O_CREATE|os.O_WRONLY, 0666)
  if err == nil {
  	log.Out = file
  } else {
  	log.Info("Failed to log to file, using default stderr")
  }

这样运行之后，源文件目录下多了个 logrus.log，日志输出到了里面。

3.3 Fields用法

logrus 不推荐使用冗长的消息来记录运行信息，它推荐使用 Fields 来进行精细化的、结构化的信息记录。

这应该是 logrus 的核心用法，所谓的结构化日志。

例如下面的记录日志的方式：

log.Fatalf("Failed to send event %s to topic %s with key %d", event, topic, key)

在 logrus 中不太提倡，鼓励使用以下方式替代之：

log.WithFields(log.Fields{
  "event": event,
  "topic": topic,
  "key": key,
}).Fatal("Failed to send event")

前面的WithFields API可以规范使用者按照其提倡的方式记录日志.但是WithFields依然是可选的,因为某些场景下,使用者确实只需要记录仪一条简单的消息.

通常,在一个应用中、或者应用的一部分中,都有一些固定的Field.比如在处理用户http请求时,上下文中,所有的日志都会有request_id和user_ip.为了避免每次记录日志都要使用log.WithFields(log.Fields{“request_id”: request_id, “user_ip”: user_ip}),我们可以创建一个logrus.Entry实例,为这个实例设置默认Fields,在上下文中使用这个logrus.Entry实例记录日志即可.

requestLogger := log.WithFields(log.Fields{"request_id": request_id, "user_ip": user_ip})
requestLogger.Info("something happened on that request") # will log request_id and user_ip
requestLogger.Warn("something not great happened")

为什么会有 log.WithFields().Fatal() 这种多次调用的写法？

因为 log.WithFields() 返回的是一个 Entry，这个 Entry 还能调用方法。

func (entry *Entry) WithField(key string, value interface{}) *Entry {
	return entry.WithFields(Fields{key: value})
}

3.4 Hook 用法

hook 有很多用法，可以将日志做进一步的处理，比如不同目的地的分发，比如额外添加字段。

这里先试试将日志写入 syslog ，根据官方说明，操作如下代码：

import (
  "os"
  "github.com/sirupsen/logrus"

  logrus_syslog "github.com/sirupsen/logrus/hooks/syslog"
  "log/syslog"
)

  hook, err := logrus_syslog.NewSyslogHook("", "", syslog.LOG_INFO, "")
  if err != nil {
    log.Error("Unable to connect to local syslog daemon")
  } else {
    log.AddHook(hook)
  }

运行过后，查看最新的系统日志，发现调试信息已经写入。

# vim /var/log/messages
Feb 27 17:03:20 VM_10_230_centos /root/test/log/__debug_bin[2194]: level=info msg="A group of walrus emerges from the ocean" animal=walrus size=10
Feb 27 17:03:20 VM_10_230_centos /root/test/log/__debug_bin[2194]: level=warning msg="The group's number increased tremendously!" number=122 omg=true
Feb 27 17:03:20 VM_10_230_centos /root/test/log/__debug_bin[2194]: level=panic msg="It's over 9000!" animal=orca size=9009
Feb 27 17:03:20 VM_10_230_centos /root/test/log/__debug_bin[2194]: level=error msg="The ice breaks!" err_animal=orca err_level=panic err_message="It's over 9000!" err_size=9009 number=100 omg=true

4 小结

Logrus 最大的特色是结构化日志记录，可以携带field；另外结合 hook 可以实现非常灵活的日志分发和内容调整。

3 logrus 的使用

1 它是什么

2 为什么是它

golang 日志库

logrus特性