README.md
1go-file-rotatelogs
2==================
3
4[](https://travis-ci.org/lestrrat/go-file-rotatelogs)
5
6[](https://godoc.org/github.com/lestrrat/go-file-rotatelogs)
7
8
9Port of [File::RotateLogs](https://metacpan.org/release/File-RotateLogs) from Perl to Go.
10
11# SYNOPSIS
12
13```go
14import (
15 "log"
16 "net/http"
17
18 apachelog "github.com/lestrrat/go-apache-logformat"
19 rotatelogs "github.com/lestrrat/go-file-rotatelogs"
20)
21
22func 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 http.ListenAndServe(":8080", apachelog.Wrap(mux, logf))
38}
39```
40
41# DESCRIPTION
42
43When you integrate this to to you app, it automatically write to logs that
44are rotated from within the app: No more disk-full alerts because you forgot
45to setup logrotate!
46
47To install, simply issue a `go get`:
48
49```
50go get github.com/lestrrat/go-file-rotatelogs
51```
52
53It's normally expected that this library is used with some other
54logging service, such as the built-in `log` library, or loggers
55such as `github.com/lestrrat/go-apache-logformat`.
56
57```go
58import(
59 "log"
60 "github.com/lestrrat/go-file-rotatelogs"
61)
62
63func main() {
64 rl, _ := rotatelogs.NewRotateLogs("/path/to/access_log.%Y%m%d%H%M")
65
66 log.SetOutput(rl)
67
68 /* elsewhere ... */
69 log.Printf("Hello, World!")
70}
71```
72
73OPTIONS
74====
75
76## Pattern (Required)
77
78The pattern used to generate actual log file names. You should use patterns
79using the strftime (3) format. For example:
80
81```go
82 rotatelogs.New("/var/log/myapp/log.%Y%m%d")
83```
84
85## Clock (default: rotatelogs.Local)
86
87You may specify an object that implements the roatatelogs.Clock interface.
88When this option is supplied, it's used to determine the current time to
89base all of the calculations on. For example, if you want to base your
90calculations in UTC, you may specify rotatelogs.UTC
91
92```go
93 rotatelogs.New(
94 "/var/log/myapp/log.%Y%m%d",
95 rotatelogs.WithClock(rotatelogs.UTC),
96 )
97```
98
99## Location
100
101This is an alternative to the `WithClock` option. Instead of providing an
102explicit clock, you can provide a location for you times. We will create
103a Clock object that produces times in your specified location, and configure
104the rotatelog to respect it.
105
106## LinkName (default: "")
107
108Path where a symlink for the actual log file is placed. This allows you to
109always check at the same location for log files even if the logs were rotated
110
111```go
112 rotatelogs.New(
113 "/var/log/myapp/log.%Y%m%d",
114 rotatelogs.WithLinkName("/var/log/myapp/current"),
115 )
116```
117
118```
119 // Else where
120 $ tail -f /var/log/myapp/current
121```
122
123If not provided, no link will be written.
124
125## RotationTime (default: 86400 sec)
126
127Interval between file rotation. By default logs are rotated every 86400 seconds.
128Note: Remember to use time.Duration values.
129
130```go
131 // Rotate every hour
132 rotatelogs.New(
133 "/var/log/myapp/log.%Y%m%d",
134 rotatelogs.WithRotationTime(time.Hour),
135 )
136```
137
138## MaxAge (default: 7 days)
139
140Time to wait until old logs are purged. By default no logs are purged, which
141certainly isn't what you want.
142Note: Remember to use time.Duration values.
143
144```go
145 // Purge logs older than 1 hour
146 rotatelogs.New(
147 "/var/log/myapp/log.%Y%m%d",
148 rotatelogs.WithMaxAge(time.Hour),
149 )
150```
151
){kind=link}
){kind=link}