vendor/github.com/lestrrat-go/file-rotatelogs/README.md

   1 file-rotatelogs
   2 ==================
   3
   4 Provide an `io.Writer` that periodically rotates log files from within the application. Port of [File::RotateLogs](https://metacpan.org/release/File-RotateLogs) from Perl to Go.
   5
   6 [![Build Status](https://travis-ci.org/lestrrat-go/file-rotatelogs.png?branch=master)](https://travis-ci.org/lestrrat-go/file-rotatelogs)
   7
   8 [![GoDoc](https://godoc.org/github.com/lestrrat-go/file-rotatelogs?status.svg)](https://godoc.org/github.com/lestrrat-go/file-rotatelogs)
   9
  10
  11 # SYNOPSIS
  12
  13 ```go
  14 import (
  15   "log"
  16   "net/http"
  17
  18   apachelog "github.com/lestrrat-go/apache-logformat"
  19   rotatelogs "github.com/lestrrat-go/file-rotatelogs"
  20 )
  21
  22 func main() {
  23   mux := http.NewServeMux()
  24   mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { ... })
  25
  26   logf, err := rotatelogs.New(
  27     "/path/to/access_log.%Y%m%d%H%M",
  28     rotatelogs.WithLinkName("/path/to/access_log"),
  29     rotatelogs.WithMaxAge(24 * time.Hour),
  30     rotatelogs.WithRotationTime(time.Hour),
  31   )
  32   if err != nil {
  33     log.Printf("failed to create rotatelogs: %s", err)
  34     return
  35   }
  36
  37   // Now you must write to logf. apache-logformat library can create
  38   // a http.Handler that only writes the approriate logs for the request
  39   // to the given handle
  40   http.ListenAndServe(":8080", apachelog.CombinedLog.Wrap(mux, logf))
  41 }
  42 ```
  43
  44 # DESCRIPTION
  45
  46 When you integrate this to to you app, it automatically write to logs that
  47 are rotated from within the app: No more disk-full alerts because you forgot
  48 to setup logrotate!
  49
  50 To install, simply issue a `go get`:
  51
  52 ```
  53 go get github.com/lestrrat-go/file-rotatelogs
  54 ```
  55
  56 It's normally expected that this library is used with some other
  57 logging service, such as the built-in `log` library, or loggers
  58 such as `github.com/lestrrat-go/apache-logformat`.
  59
  60 ```go
  61 import(
  62   "log"
  63   "github.com/lestrrat-go/file-rotatelogs"
  64 )
  65
  66 func main() {
  67   rl, _ := rotatelogs.New("/path/to/access_log.%Y%m%d%H%M")
  68
  69   log.SetOutput(rl)
  70
  71   /* elsewhere ... */
  72   log.Printf("Hello, World!")
  73 }
  74 ```
  75
  76 OPTIONS
  77 ====
  78
  79 ## Pattern (Required)
  80
  81 The pattern used to generate actual log file names. You should use patterns
  82 using the strftime (3) format. For example:
  83
  84 ```go
  85   rotatelogs.New("/var/log/myapp/log.%Y%m%d")
  86 ```
  87
  88 ## Clock (default: rotatelogs.Local)
  89
  90 You may specify an object that implements the roatatelogs.Clock interface.
  91 When this option is supplied, it's used to determine the current time to
  92 base all of the calculations on. For example, if you want to base your
  93 calculations in UTC, you may specify rotatelogs.UTC
  94
  95 ```go
  96   rotatelogs.New(
  97     "/var/log/myapp/log.%Y%m%d",
  98     rotatelogs.WithClock(rotatelogs.UTC),
  99   )
 100 ```
 101
 102 ## Location
 103
 104 This is an alternative to the `WithClock` option. Instead of providing an
 105 explicit clock, you can provide a location for you times. We will create
 106 a Clock object that produces times in your specified location, and configure
 107 the rotatelog to respect it.
 108
 109 ## LinkName (default: "")
 110
 111 Path where a symlink for the actual log file is placed. This allows you to
 112 always check at the same location for log files even if the logs were rotated
 113
 114 ```go
 115   rotatelogs.New(
 116     "/var/log/myapp/log.%Y%m%d",
 117     rotatelogs.WithLinkName("/var/log/myapp/current"),
 118   )
 119 ```
 120
 121 ```
 122   // Else where
 123   $ tail -f /var/log/myapp/current
 124 ```
 125
 126 If not provided, no link will be written.
 127
 128 ## RotationTime (default: 86400 sec)
 129
 130 Interval between file rotation. By default logs are rotated every 86400 seconds.
 131 Note: Remember to use time.Duration values.
 132
 133 ```go
 134   // Rotate every hour
 135   rotatelogs.New(
 136     "/var/log/myapp/log.%Y%m%d",
 137     rotatelogs.WithRotationTime(time.Hour),
 138   )
 139 ```
 140
 141 ## MaxAge (default: 7 days)
 142
 143 Time to wait until old logs are purged. By default no logs are purged, which
 144 certainly isn't what you want.
 145 Note: Remember to use time.Duration values.
 146
 147 ```go
 148   // Purge logs older than 1 hour
 149   rotatelogs.New(
 150     "/var/log/myapp/log.%Y%m%d",
 151     rotatelogs.WithMaxAge(time.Hour),
 152   )
 153 ```
 154
 155 ## RotationCount (default: -1)
 156
 157 The number of files should be kept. By default, this option is disabled.
 158
 159 Note: MaxAge should be disabled by specifing `WithMaxAge(-1)` explicitly.
 160
 161 ```go
 162   // Purge logs except latest 7 files
 163   rotatelogs.New(
 164     "/var/log/myapp/log.%Y%m%d",
 165     rotatelogs.WithMaxAge(-1),
 166     rotatelogs.WithRotationCount(7),
 167   )
 168 ```
 169
 170 ## Handler (default: nil)
 171
 172 Sets the event handler to receive event notifications from the RotateLogs
 173 object. Currently only supported event type is FiledRotated
 174
 175 ```go
 176   rotatelogs.New(
 177     "/var/log/myapp/log.%Y%m%d",
 178     rotatelogs.Handler(rotatelogs.HandlerFunc(func(e Event) {
 179       if e.Type() != rotatelogs.FileRotatedEventType {
 180         return
 181       }
 182
 183       // Do what you want with the data. This is just an idea:
 184       storeLogFileToRemoteStorage(e.(*FileRotatedEvent).PreviousFile())
 185     })),
 186   )
 187 ```
 188
 189 ## ForceNewFile
 190
 191 Ensure a new file is created every time New() is called. If the base file name
 192 already exists, an implicit rotation is performed.
 193
 194 ```go
 195   rotatelogs.New(
 196     "/var/log/myapp/log.%Y%m%d",
 197     rotatelogs.ForceNewFile(),
 198   )
 199 ```
 200
 201 ## ForceNewFile
 202
 203 Ensure a new file is created every time New() is called. If the base file name
 204 already exists, an implicit rotation is performed.
 205
 206 ```go
 207   rotatelogs.New(
 208     "/var/log/myapp/log.%Y%m%d",
 209     rotatelogs.ForceNewFile(),
 210   )
 211 ```
 212
 213 # Rotating files forcefully
 214
 215 If you want to rotate files forcefully before the actual rotation time has reached,
 216 you may use the `Rotate()` method. This method forcefully rotates the logs, but
 217 if the generated file name clashes, then a numeric suffix is added so that
 218 the new file will forcefully appear on disk.
 219
 220 For example, suppose you had a pattern of '%Y.log' with a rotation time of
 221 `86400` so that it only gets rotated every year, but for whatever reason you
 222 wanted to rotate the logs now, you could install a signal handler to
 223 trigger this rotation:
 224
 225 ```go
 226 rl := rotatelogs.New(...)
 227
 228 signal.Notify(ch, syscall.SIGHUP)
 229
 230 go func(ch chan os.Signal) {
 231   <-ch
 232   rl.Rotate()
 233 }()
 234 ```
 235
 236 And you will get a log file name in like `2018.log.1`, `2018.log.2`, etc.