提供一个io.Writer ，在应用中周期旋转日志文件。Go语言实现 File::RotateLogs。

SYNOPSIS

import (
  "log"
  "net/http"
  apachelog "github.com/lestrrat-go/apache-logformat"
  rotatelogs "github.com/lestrrat-go/file-rotatelogs"
)
func main() {
  mux := http.NewServeMux()
  mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { ... })
  logf, err := rotatelogs.New(
    "/path/to/access_log.%Y%m%d%H%M",
    rotatelogs.WithLinkName("/path/to/access_log"),
    rotatelogs.WithMaxAge(24 * time.Hour),
    rotatelogs.WithRotationTime(time.Hour),
  )
  if err != nil {
    log.Printf("failed to create rotatelogs: %s", err)
    return
  }
  // Now you must write to logf. apache-logformat library can create
  // a http.Handler that only writes the approriate logs for the request
  // to the given handle
  http.ListenAndServe(":8080", apachelog.CombinedLog.Wrap(mux, logf))
}

DESCRIPTION

当你把这个集成到你的应用程序中，它自动写入日志，从应用程序内旋转:

要安装，只需发出go get命令:

go get github.com/lestrrat-go/file-rotatelogs

通常期望这个库与其他一些日志服务一起使用，比如内置的日志库，或者像github.com/lestrrat-go/apache-logformat这样的日志记录器。

import(
  "log"
  "github.com/lestrrat-go/file-rotatelogs"
)
func main() {
  rl, _ := rotatelogs.New("/path/to/access_log.%Y%m%d%H%M")
  log.SetOutput(rl)
  /* elsewhere ... */
  log.Printf("Hello, World!")
}

OPTIONS

Partten (Required)

用于生成实际日志文件名的模式。您应该使用strftime(3)格式的模式。例如:

  rotatelogs.New("/var/log/myapp/log.%Y%m%d")

Clock (default:rotatelogs.Local)

你可以指定一个对象来实现roatatlogs。时钟界面。当提供此选项时，将使用它来确定当前时间，以便进行所有计算。例如，如果你想在UTC中计算，你可以指定rotatlogs.UTC

  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithClock(rotatelogs.UTC),
  )

Location

这是WithClock选项的另一种选择。您可以为您的时间提供一个位置，而不是提供显式的时钟。我们将创建一个Clock对象，它在您指定的位置产生时间，并配置rotatelog以尊重它。

LinkName (default:””)

放置实际日志文件的符号链接的路径。这允许您始终在相同的位置检查日志文件，即使日志是旋转的。

  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithLinkName("/var/log/myapp/current"),
  )

  // Else where
  $ tail -f /var/log/myapp/current

与主日志路径共享同一父目录的链接将得到特殊处理:即，链接路径将相对于主日志文件。

如果没有提供，没有链接将被写。

RotationTime (default:86400 sec)

文件旋转的间隔。缺省情况下，日志周期为86400秒。注意:记住要利用时间。持续时间值。

  // Rotate every hour
  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithRotationTime(time.Hour),
  )

MaxAge (default: 7 days)

等待旧日志被清除的时间。默认情况下，不会清除任何日志，这肯定不是您想要的。注意:记住要利用时间。持续时间值。

  // Purge logs older than 1 hour
  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithMaxAge(time.Hour),
  )

RotationCount (default：-1)

文件的数量应该保留。默认情况下，此选项是禁用的。
注意:MaxAge应该通过显式指定WithMaxAge(-1)来禁用。

  // Purge logs except latest 7 files
  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithMaxAge(-1),
    rotatelogs.WithRotationCount(7),
  )

Handler (default:nil)

设置事件处理程序以从RotateLogs对象接收事件通知。当前仅支持的事件类型是filedrotate

  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithHandler(rotatelogs.HandlerFunc(func(e rotatelogs.Event) {
      if e.Type() != rotatelogs.FileRotatedEventType {
        return
      }
      // Do what you want with the data. This is just an idea:
      storeLogFileToRemoteStorage(e.(*rotatelogs.FileRotatedEvent).PreviousFile())
    })),
  )

ForceNewFile

确保每次调用new()时都创建一个新文件。如果基本文件名已经存在，则执行隐式旋转。

  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.ForceNewFile(),
  )

Rotating files forcefully

如果您想在实际旋转时间到达之前强制旋转文件,你可以使用Rotate()方法。此方法强制旋转日志，但如果生成的文件名冲突，则添加数字后缀，以便新文件强制出现在磁盘上。

例如，假设你有一个’%Y.log’的模式，其旋转时间为86400，所以它每年才会旋转，但无论出于什么原因，你现在想要旋转日志，你可以安装一个信号处理程序来触发这种旋转:

rl := rotatelogs.New(...)
signal.Notify(ch, syscall.SIGHUP)
go func(ch chan os.Signal) {
  <-ch
  rl.Rotate()
}()

你会得到一个日志文件名，比如2018.log。2018.日志。2,等等。