go語言日誌框架logrus

轉載自李文周的博客

logrus介紹
Logrus是Go（golang）的結構化logger，與標準庫logger完全API兼容。

它有以下特點：

1. 完全兼容標準日誌庫，擁有七種日誌級別：Trace, Debug, Info, Warning, Error, Fataland Panic。
2. 可擴展的Hook機制，允許使用者通過Hook的方式將日誌分發到任意地方，如本地文件系統，logstash，elasticsearch或者mq等，或者通過Hook定義日誌內容和格式等
3. 可選的日誌輸出格式，內置了兩種日誌格式JSONFormater和TextFormatter，還可以自定義日誌格式
4. Field機制，通過Filed機制進行結構化的日誌記錄
5. 線程安全

---

依賴引入

go get github.com/sirupsen/logrus

---

基本示例
使用Logrus最簡單的方法是簡單的包級導出日誌程序:

package main

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

func main() {
  log.WithFields(log.Fields{
    "animal": "dog",
  }).Info("一條舔狗出現了。")
}

---

全局日誌
對於更高級的用法，例如在同一應用程序記錄到多個位置，你還可以創建logrus Logger的實例：

package main

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

// 創建一個新的logger實例。可以創建任意多個。
var log = logrus.New()

func main() {
  // 設置日誌輸出爲os.Stdout
  log.Out = os.Stdout

  // 可以設置像文件等任意`io.Writer`類型作爲日誌輸出
  // file, err := os.OpenFile("logrus.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
  // if err == nil {
  //  log.Out = file
  // } else {
  //  log.Info("Failed to log to file, using default stderr")
  // }

  log.WithFields(logrus.Fields{
    "animal": "dog",
    "size":   10,
  }).Info("一羣舔狗出現了。")
}

---

日誌級別
Logrus有七個日誌級別：Trace, Debug, Info, Warning, Error, Fataland Panic。

log.Trace(“Something very low level.”)
log.Debug(“Useful debugging information.”)
log.Info(“Something noteworthy happened!”)
log.Warn(“You should probably take a look at this.”)
log.Error(“Something failed but I’m not quitting.”)
// 記完日誌後會調用os.Exit(1)
log.Fatal(“Bye.”)
// 記完日誌後會調用 panic()
log.Panic(“I’m bailing.”)

設置日誌級別
你可以在Logger上設置日誌記錄級別，然後它只會記錄具有該級別或以上級別任何內容的條目：

// 會記錄info及以上級別 (warn, error, fatal, panic)
log.SetLevel(log.InfoLevel)

如果你的程序支持debug或環境變量模式，設置log.Level = logrus.DebugLevel會很有幫助。

---

字段
Logrus鼓勵通過日誌字段進行謹慎的結構化日誌記錄，而不是冗長的、不可解析的錯誤消息。

例如，區別於使用log.Fatalf(“Failed to send event %s to topic %s with key %d”)，你應該使用如下方式記錄更容易發現的內容:

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

WithFields的調用是可選的。

---

默認字段
通常，將一些字段始終附加到應用程序的全部或部分的日誌語句中會很有幫助。例如，你可能希望始終在請求的上下文中記錄request_id和user_ip。

區別於在每一行日誌中寫上log.WithFields(log.Fields{“request_id”: request_id, “user_ip”: user_ip})，你可以向下面的示例代碼一樣創建一個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")

---

日誌條目
除了使用WithField或WithFields添加的字段外，一些字段會自動添加到所有日誌記錄事中:

time：記錄日誌時的時間戳
msg：記錄的日誌信息
level：記錄的日誌級別

---

Hooks
logrus的hook接口定義如下，其原理是每此寫入日誌時攔截，修改logrus.Entry。

// logrus在記錄Levels()返回的日誌級別的消息時會觸發HOOK，
// 按照Fire方法定義的內容修改logrus.Entry。
type Hook interface {
    Levels() []Level
    Fire(*Entry) error
}

一個簡單自定義hook如下，DefaultFieldHook定義會在所有級別的日誌消息中加入默認字段appName=“myAppName”。

type DefaultFieldHook struct {
}

func (hook *DefaultFieldHook) Fire(entry *log.Entry) error {
    entry.Data["appName"] = "MyAppName"
    return nil
}

func (hook *DefaultFieldHook) Levels() []log.Level {
    return log.AllLevels
}

hook的使用也很簡單，在初始化前調用log.AddHook(hook)添加相應的hook即可。

logrus官方僅僅內置了syslog的hook。
你可以添加日誌級別的鉤子（Hook）。例如，向異常跟蹤服務發送Error、Fatal和Panic、信息到StatsD或同時將日誌發送到多個位置，例如syslog。

import (
  log "github.com/sirupsen/logrus"
  "gopkg.in/gemnasium/logrus-airbrake-hook.v2" // the package is named "airbrake"
  logrus_syslog "github.com/sirupsen/logrus/hooks/syslog"
  "log/syslog"
)

func init() {

  // Use the Airbrake hook to report errors that have Error severity or above to
  // an exception tracker. You can create custom hooks, see the Hooks section.
  log.AddHook(airbrake.NewHook(123, "xyz", "production"))

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

意：Syslog鉤子還支持連接到本地syslog（例如. “/dev/log” or “/var/run/syslog” or “/var/run/log”)。有關詳細信息，請查看syslog hook README。

---

格式化
logrus內置以下兩種日誌格式化程序：

1. logrus.TextFormatter
2. ogrus.JSONFormatter

還支持一些第三方的格式化程序，詳見項目首頁。

---

記錄函數名
如果你希望將調用的函數名添加爲字段，請通過以下方式設置：

log.SetReportCaller(true)

這會將調用者添加爲”method”，如下所示：

{"animal":"penguin","level":"fatal","method":"github.com/sirupsen/arcticcreatures.migrate","msg":"a penguin swims by",
"time":"2014-03-10 19:57:38.562543129 -0400 EDT"}

注意：，開啓這個模式會增加性能開銷。

---

線程安全
默認的logger在併發寫的時候是被mutex保護的，比如當同時調用hook和寫log時mutex就會被請求，有另外一種情況，文件是以appending mode打開的， 此時的併發操作就是安全的，可以用logger.SetNoLock()來關閉它。

---

gin框架使用logrus

// a gin with logrus demo

var log = logrus.New()

func init() {
	// Log as JSON instead of the default ASCII formatter.
	log.Formatter = &logrus.JSONFormatter{}
	// Output to stdout instead of the default stderr
	// Can be any io.Writer, see below for File example
	f, _ := os.Create("./gin.log")
	log.Out = f
	gin.SetMode(gin.ReleaseMode)
	gin.DefaultWriter = log.Out
	// Only log the warning severity or above.
	log.Level = logrus.InfoLevel
}

func main() {
	// 創建一個默認的路由引擎
	r := gin.Default()
	// GET：請求方式；/hello：請求的路徑
	// 當客戶端以GET方法請求/hello路徑時，會執行後面的匿名函數
	r.GET("/hello", func(c *gin.Context) {
		log.WithFields(logrus.Fields{
			"animal": "walrus",
			"size":   10,
		}).Warn("A group of walrus emerges from the ocean")
		// c.JSON：返回JSON格式的數據
		c.JSON(200, gin.H{
			"message": "Hello world!",
		})
	})
	// 啓動HTTP服務，默認在0.0.0.0:8080啓動服務
	r.Run()
}