@@ -13,24 +13,32 @@ import (
1313 "time"
1414)
1515
16+// AuthStatus defines the different types of auth logging that occur
1617type AuthStatus string
1718
1819const (
19− // Default logging formats
20+ // DefaultStandardLoggingFormat defines the default standard log format
2021 DefaultStandardLoggingFormat = "[{{.Timestamp}}] [{{.File}}] {{.Message}}"
21− DefaultAuthLoggingFormat = "{{.Client}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}"
22− DefaultRequestLoggingFormat = "{{.Client}} - {{.Username}} [{{.Timestamp}}] {{.Host}} {{.RequestMethod}} {{.Upstream}} {{.RequestURI}} {{.Protocol}} {{.UserAgent}} {{.StatusCode}} {{.ResponseSize}} {{.RequestDuration}}"
22+ // DefaultAuthLoggingFormat defines the default auth log format
23+ DefaultAuthLoggingFormat = "{{.Client}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}"
24+ // DefaultRequestLoggingFormat defines the default request log format
25+ DefaultRequestLoggingFormat = "{{.Client}} - {{.Username}} [{{.Timestamp}}] {{.Host}} {{.RequestMethod}} {{.Upstream}} {{.RequestURI}} {{.Protocol}} {{.UserAgent}} {{.StatusCode}} {{.ResponseSize}} {{.RequestDuration}}"
2326
24− // Auth statuses
27+ // AuthSuccess indicates that an auth attempt has succeeded explicitly
2528 AuthSuccess AuthStatus = "AuthSuccess"
29+ // AuthFailure indicates that an auth attempt has failed explicitly
2630 AuthFailure AuthStatus = "AuthFailure"
27− AuthError AuthStatus = "AuthError"
28−
29− // General logging config
30− Llongfile = 1 << iota // full file name and line number: /a/b/c/d.go:23
31− Lshortfile // final file name element and line number: d.go:23. overrides Llongfile
32− LUTC // use UTC rather than the local time zone
33− LstdFlags = Lshortfile // initial values for the standard logger
31+ // AuthError indicates that an auth attempt has failed due to an error
32+ AuthError AuthStatus = "AuthError"
33+
34+ // Llongfile flag to log full file name and line number: /a/b/c/d.go:23
35+ Llongfile = 1 << iota
36+ // Lshortfile flag to log final file name element and line number: d.go:23. overrides Llongfile
37+ Lshortfile
38+ // LUTC flag to log UTC datetime rather than the local time zone
39+ LUTC
40+ // LstdFlags flag for initial values for the logger
41+ LstdFlags = Lshortfile
3442)
3543
3644// These are the containers for all values that are available as variables in the logging formats.
@@ -68,6 +76,11 @@ type reqLogMessageData struct {
6876 Username string
6977}
7078
79+// A Logger represents an active logging object that generates lines of
80+// output to an io.Writer passed through a formatter. Each logging
81+// operation makes a single call to the Writer's Write method. A Logger
82+// can be used simultaneously from multiple goroutines; it guarantees to
83+// serialize access to the Writer.
7184type Logger struct {
7285 mu sync.Mutex
7386 flag int
@@ -96,23 +109,6 @@ func New(flag int) *Logger {
96109
97110var std = New(LstdFlags)
98111
99−// Cheap integer to fixed-width decimal ASCII. Give a negative width to avoid zero-padding.
100−func itoa(buf *[]byte, i int, wid int) {
101− // Assemble decimal in reverse order.
102− var b [20]byte
103− bp := len(b) - 1
104− for i >= 10 || wid > 1 {
105− wid--
106− q := i / 10
107− b[bp] = byte('0' + i - q*10)
108− bp--
109− i = q
110− }
111− // i < 10
112− b[bp] = byte('0' + i)
113− *buf = append(*buf, b[bp:]...)
114−}
115−
116112// Output a standard log template with a simple message.
117113// Write a final newline at the end of every message.
118114func (l *Logger) Output(calldepth int, message string) {
@@ -139,9 +135,9 @@ func (l *Logger) Output(calldepth int, message string) {
139135 l.writer.Write([]byte("\n"))
140136}
141137
142−// Print auth details to the logger. Requires an http.Request to log details.
143−// Remaining arguments are handled in the manner of fmt.Sprintf.
144−// Writes a final newline to the end of every message.
138+// PrintAuth writes auth info to the logger. Requires an http.Request to
139+// log request details. Remaining arguments are handled in the manner of
140+// fmt.Sprintf. Writes a final newline to the end of every message.
145141func (l *Logger) PrintAuth(username string, req *http.Request, status AuthStatus, format string, a ...interface{}) {
146142 if !l.authEnabled {
147143 return
@@ -173,8 +169,9 @@ func (l *Logger) PrintAuth(username string, req *http.Request, status AuthStatus
173169 l.writer.Write([]byte("\n"))
174170}
175171
176−// Print HTTP request details to the Logger.
177−// Writes a final newline to the end of every message.
172+// PrintReq writes request details to the Logger using the http.Request,
173+// url, and timestamp of the request. Writes a final newline to the end
174+// of every message.
178175func (l *Logger) PrintReq(username, upstream string, req *http.Request, url url.URL, ts time.Time, status int, size int) {
179176 if !l.reqEnabled {
180177 return
@@ -219,7 +216,9 @@ func (l *Logger) PrintReq(username, upstream string, req *http.Request, url url.
219216 l.writer.Write([]byte("\n"))
220217}
221218
222−// Obtains file and line number info for the standard output log
219+// GetFileLineString will find the caller file and line number
220+// taking in to account the calldepth to iterate up the stack
221+// to find the non-logging call location.
223222func (l *Logger) GetFileLineString(calldepth int) string {
224223 var file string
225224 var line int
@@ -245,7 +244,7 @@ func (l *Logger) GetFileLineString(calldepth int) string {
245244 return fmt.Sprintf("%s:%d", file, line)
246245}
247246
248−// Parse an HTTP request for the client/remote IP
247+// GetClient parses an HTTP request for the client/remote IP address.
249248func GetClient(req *http.Request) string {
250249 client := req.Header.Get("X-Real-IP")
251250 if client == "" {
@@ -259,7 +258,7 @@ func GetClient(req *http.Request) string {
259258 return client
260259}
261260
262−// Returns a formatted timestamp
261+// FormatTimestamp returns a formatted timestamp.
263262func (l *Logger) FormatTimestamp(ts time.Time) string {
264263 if l.flag&LUTC != 0 {
265264 ts = ts.UTC()
@@ -282,42 +281,42 @@ func (l *Logger) SetFlags(flag int) {
282281 l.flag = flag
283282}
284283
285−// Set all logging enabled for the logger.
284+// SetStandardEnabled enables or disables standard logging.
286285func (l *Logger) SetStandardEnabled(e bool) {
287286 l.mu.Lock()
288287 defer l.mu.Unlock()
289288 l.stdEnabled = e
290289}
291290
292−// Set auth logging enabled for the standard logger
291+// SetAuthEnabled enables or disables auth logging.
293292func (l *Logger) SetAuthEnabled(e bool) {
294293 l.mu.Lock()
295294 defer l.mu.Unlock()
296295 l.authEnabled = e
297296}
298297
299−// Set request logging enabled for the standard logger
298+// SetReqEnabled enabled or disables request logging.
300299func (l *Logger) SetReqEnabled(e bool) {
301300 l.mu.Lock()
302301 defer l.mu.Unlock()
303302 l.reqEnabled = e
304303}
305304
306−// Set the output template for the standard logger
305+// SetStandardTemplate sets the template for standard logging.
307306func (l *Logger) SetStandardTemplate(t string) {
308307 l.mu.Lock()
309308 defer l.mu.Unlock()
310309 l.stdLogTemplate = template.Must(template.New("std-log").Parse(t))
311310}
312311
313−// Set the auth template for the standard logger
312+// SetAuthTemplate sets the template for auth logging.
314313func (l *Logger) SetAuthTemplate(t string) {
315314 l.mu.Lock()
316315 defer l.mu.Unlock()
317316 l.authTemplate = template.Must(template.New("auth-log").Parse(t))
318317}
319318
320−// Set the request template for the standard logger
319+// SetReqTemplate sets the template for request logging.
321320func (l *Logger) SetReqTemplate(t string) {
322321 l.mu.Lock()
323322 defer l.mu.Unlock()
@@ -326,7 +325,7 @@ func (l *Logger) SetReqTemplate(t string) {
326325
327326// These functions utilize the standard logger.
328327
329−// Returns a formatted timestamp for the standard logger.
328+// FormatTimestamp returns a formatted timestamp for the standard logger.
330329func FormatTimestamp(ts time.Time) string {
331330 return std.FormatTimestamp(ts)
332331}
@@ -348,32 +347,38 @@ func SetOutput(w io.Writer) {
348347 std.writer = w
349348}
350349
351−// Set output logging enabled for the standard logger
350+// SetStandardEnabled enables or disables standard logging for the
351+// standard logger.
352352func SetStandardEnabled(e bool) {
353353 std.SetStandardEnabled(e)
354354}
355355
356−// Set auth logging enabled for the standard logger
356+// SetAuthEnabled enables or disables auth logging for the standard
357+// logger.
357358func SetAuthEnabled(e bool) {
358359 std.SetAuthEnabled(e)
359360}
360361
361−// Set request logging enabled for the standard logger
362+// SetReqEnabled enables or disables request logging for the
363+// standard logger.
362364func SetReqEnabled(e bool) {
363365 std.SetReqEnabled(e)
364366}
365367
366−// Set the output template for the standard logger
368+// SetStandardTemplate sets the template for standard logging for
369+// the standard logger.
367370func SetStandardTemplate(t string) {
368371 std.SetStandardTemplate(t)
369372}
370373
371−// Set the auth template for the standard logger
374+// SetAuthTemplate sets the template for auth logging for the
375+// standard logger.
372376func SetAuthTemplate(t string) {
373377 std.SetAuthTemplate(t)
374378}
375379
376−// Set the request template for the standard logger
380+// SetReqTemplate sets the template for request logging for the
381+// standard logger.
377382func SetReqTemplate(t string) {
378383 std.SetReqTemplate(t)
379384}
@@ -441,7 +446,7 @@ func PrintAuthf(username string, req *http.Request, status AuthStatus, format st
441446 std.PrintAuth(username, req, status, format, a...)
442447}
443448
444−// PrintAuthf writes request details to the standard logger.
449+// PrintReq writes request details to the standard logger.
445450func PrintReq(username, upstream string, req *http.Request, url url.URL, ts time.Time, status int, size int) {
446451 std.PrintReq(username, upstream, req, url, ts, status, size)
447452}