log 包

log 包提供了一组基础的日志 API 和一个使用了 stderr 进行输出的标准实现。

标准接口如下：

  1. // Level is log level of verboser. We strongly recommend you to
  2. // follow the rules:
  3. // 1. Use LevelDebug for debug log.
  4. // 2. Use 1 for important but not frequent log.
  5. // 3. Use 2 for important and frequent log.
  6. // 4. Use 3 for not important and not frequent log.
  7. // 5. Use 4 for not important but frequent log.
  8. // 6. Use [5, LevelDebug) only if you want to custom log levels.
  9. type Level int32
  11. const (
  12.     // LevelDebug is for debug info.
  13.     LevelDebug Level = math.MaxInt32
  14. )
  16. // Severity has four classes to correspond with log situation.
  17. type Severity string
  19. const (
  20.     // SeverityInfo is for usual log.
  21.     SeverityInfo Severity = "INFO"
  22.     // SeverityWarning is for warning.
  23.     SeverityWarning Severity = "WARN"
  24.     // SeverityError is for error.
  25.     SeverityError Severity = "ERROR"
  26.     // SeverityFatal is for panic error. The severity means that
  27.     // a logger will output the error and exit immediately.
  28.     // It can't be recovered.
  29.     SeverityFatal Severity = "FATAL"
  30. )
  32. // Verboser is an interface type that implements Info(f|ln) .
  33. // See the documentation of V for more information.
  34. type Verboser interface {
  35.     // Info logs to the INFO log.
  36.     // Arguments are handled in the manner of fmt.Println; a newline is appended if missing.
  37.     Info(...interface{})
  38.     // Infof logs to the INFO log.
  39.     // Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.
  40.     Infof(string, ...interface{})
  41.     // Infoln logs to the INFO log.
  42.     // Arguments are handled in the manner of fmt.Println; a newline is appended if missing.
  43.     Infoln(...interface{})
  44. }
  46. // Logger provides a set of methods to output log.
  47. type Logger interface {
  48.     Verboser
  49.     // V reports whether verbosity at the call site is at least the requested level.
  50.     // The returned value is a Verboser, which implements Info, Infof
  51.     // and Infoln. These methods will write to the Info log if called.
  52.     V(Level) Verboser
  53.     // Warning logs to the WARNING logs.
  54.     // Arguments are handled in the manner of fmt.Print; a newline is appended if missing.
  55.     Warning(...interface{})
  56.     // Warningf logs to the WARNING logs.
  57.     // Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.
  58.     Warningf(string, ...interface{})
  59.     // Warningln logs to the WARNING logs.
  60.     // Arguments are handled in the manner of fmt.Println; a newline is appended if missing.
  61.     Warningln(...interface{})
  62.     // Error logs to the ERROR logs.
  63.     // Arguments are handled in the manner of fmt.Print; a newline is appended if missing.
  64.     Error(...interface{})
  65.     // Errorf logs to the ERROR logs.
  66.     // Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.
  67.     Errorf(string, ...interface{})
  68.     // Errorln logs to the ERROR logs.
  69.     // Arguments are handled in the manner of fmt.Println; a newline is appended if missing.
  70.     Errorln(...interface{})
  71.     // Fatal logs to the FATAL logs, then calls os.Exit(1).
  72.     // Arguments are handled in the manner of fmt.Print; a newline is appended if missing.
  73.     Fatal(...interface{})
  74.     // Fatalf logs to the FATAL logs, then calls os.Exit(1).
  75.     // Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.
  76.     Fatalf(string, ...interface{})
  77.     // Fatalln logs to the FATAL logs, then calls os.Exit(1).
  78.     // Arguments are handled in the manner of fmt.Println; a newline is appended if missing.
  79.     Fatalln(...interface{})
  80.     // Clone clones current logger with new wrapper.
  81.     // A positive wrapper indicates how many wrappers outside the logger.
  82.     // A negative wrapper indicates how many wrappers should be stripped.
  83.     Clone(wrapper int) Logger
  84. }

这套日志 API 参考了 glog 的 golang API，并且允许用户接入其他日志系统。

在实现一个自定义的 logger 之前，需要知道以下几件事情：

  1. log 包有一个默认的 logger，使用的是 StdLogger。可以通过 SetDefaultLogger() 变更。
  2. 对于不需要输出日志的场景，使用 SilentLogger 的实例而不是 nil.
  3. 正确实现 logger 的 Clone 方法。Clone 方法用于在对 logger 进行包装的时候，获取正确层级的调用栈信息。
  4. 在 Fatal* 时候，使用 os.Exit(1) 进行退出，而不是使用其他错误码（除非业务有要求）。这是标准库的日志包使用的退出码。