logger

README

Logger

Logger is an HTTP middleware for Go that logs web requests to an io.Writer (the default being os.Stdout). It's a standard net/http Handler, and can be used with many frameworks or directly with Go's net/http package.

Usage

// main.go
package main

import (
    "log"
    "net/http"

    "github.com/unrolled/logger"
)

var myHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("hello world"))
})

func main() {
    loggerWithConfigMiddleware := logger.New(logger.Options{
        Prefix: "MySampleWebApp",
        RemoteAddressHeaders: []string{"X-Forwarded-For"},
        OutputFlags: log.LstdFlags,
    })

    // loggerWithDefaults := logger.New()

    app := loggerMiddleware.Handler(myHandler)
    http.ListenAndServe("0.0.0.0:3000", app)
}

A simple GET request to "/info/" will output:

[MySampleWebApp] 2014/11/21 14:11:21 (12.34.56.78) "GET /info/ HTTP/1.1" 200 11 12.54µs

Here's a breakdown of what the values mean: [SuppliedPrefix] Date Time (RemoteIP) "Method RequestURI Protocol" StatusCode Size Time. Note that the Date Time is controlled by the output flags. See http://golang.org/pkg/log/#pkg-constants.

Be sure to use the Logger middleware as the very first handler in the chain. This will ensure that your subsequent handlers (like Recovery) will always be logged.

Available Options

Logger comes with a variety of configuration options (Note: these are not the default option values. See the defaults below.):

// ...
l := logger.New(logger.Options{
    Prefix: "myApp", // Prefix is the outputted keyword in front of the log message. Logger automatically wraps the prefix in square brackets (ie. [myApp] ) unless the `DisableAutoBrackets` is set to true. A blank value will not have brackets added. Default is blank (with no brackets).
    DisableAutoBrackets: false, // DisableAutoBrackets if set to true, will remove the prefix and square brackets. Default is false.
    RemoteAddressHeaders: []string{"X-Forwarded-For"}, // RemoteAddressHeaders is a list of header keys that Logger will look at to determine the proper remote address. Useful when using a proxy like Nginx: `[]string{"X-Forwarded-For"}`. Default is an empty slice, and thus will use `reqeust.RemoteAddr`.
    Out: os.Stdout, // Out is the destination to which the logged data will be written too. Default is `os.Stdout`.
    OutputFlags: log.Ldate | log.Ltime, // OutputFlags defines the logging properties. See http://golang.org/pkg/log/#pkg-constants. To disable all flags, set this to `-1`. Defaults to log.LstdFlags (2009/01/23 01:23:23).
    IgnoredRequestURIs: []string{"/favicon.ico"}, // IgnoredRequestURIs is a list of path values we do not want logged out. Exact match only!
})
// ...

Default Options

These are the preset options for Logger:

l := logger.New()

// Is the same as the default configuration options:

l := logger.New(logger.Options{
    Prefix: "",
    DisableAutoBrackets: false,
    RemoteAddressHeaders: []string{},
    Out: os.Stdout,
    OutputFlags log.LstdFlags,
    IgnoredRequestURIs: []string{},
})

Capturing the proper remote address

If your app is behind a load balancer or proxy, the default Request.RemoteAddr will likely be wrong. To ensure you're logging the correct IP address, you can set the RemoteAddressHeaders option to a list of header names you'd like to use. Logger will iterate over the slice and use the first header value it finds. If it finds none, it will default to the Request.RemoteAddr.

package main

import (
    "log"
    "net/http"

    "github.com/unrolled/logger"
)

var myHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("hello world"))
})

func main() {
    loggerWithConfigMiddleware := logger.New(logger.Options{
        RemoteAddressHeaders: []string{"X-Real-IP", "X-Forwarded-For"},
    })

    app := loggerMiddleware.Handler(myHandler)
    http.ListenAndServe("0.0.0.0:3000", app)
}

Documentation

Overview

Package logger is an HTTP middleware for Go that logs web requests to an io.Writer.

package main

import (
    "log"
    "net/http"

    "github.com/unrolled/logger"
)

var myHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("hello world"))
})

func main() {
    loggerMiddleware := logger.New(logger.Options{
        Prefix: "MySampleWebApp",
        RemoteAddressHeaders: []string{"X-Forwarded-Proto"},
        OutputFlags: log.LstdFlags,
    })

    // loggerWithDefaults := logger.New()

    app := loggerMiddleware.Handler(myHandler)
    http.ListenAndServe("0.0.0.0:3000", app)
}

A simple GET request to "/info/" will output:

[MySampleWebApp] 2014/11/21 14:11:21 (12.34.56.78) "GET /info/ HTTP/1.1" 200 11 12.54µs

Here's a breakdown of what the values mean:

[SuppliedPrefix] Date Time (RemoteIP) "Method RequestURI Protocol" StatusCode Size Time

Index

• type Logger
  • func New(opts ...Options) *Logger
  • func (l *Logger) Handler(next http.Handler) http.Handler
• type Options

Types

type Logger

type Logger struct {
	*log.Logger
	// contains filtered or unexported fields
}

Logger is a HTTP middleware handler that logs a request. Outputted information includes status, method, URL, remote address, size, and the time it took to process the request.

func New

func New(opts ...Options) *Logger

New returns a new Logger instance.

func (*Logger) Handler

func (l *Logger) Handler(next http.Handler) http.Handler

Handler wraps an HTTP handler and logs the request as necessary.

type Options

type Options struct {
	// Prefix is the outputted keyword in front of the log message. Logger automatically wraps the prefix in square brackets (ie. [myApp] ) unless the `DisableAutoBrackets` is set to true. A blank value will not have brackets added. Default is blank (with no brackets).
	Prefix string
	// DisableAutoBrackets if set to true, will remove the prefix and square brackets. Default is false.
	DisableAutoBrackets bool
	// RemoteAddressHeaders is a list of header keys that Logger will look at to determine the proper remote address. Useful when using a proxy like Nginx: `[]string{"X-Forwarded-Proto"}`. Default is an empty slice, and thus will use `reqeust.RemoteAddr`.
	RemoteAddressHeaders []string
	// Out is the destination to which the logged data will be written too. Default is `os.Stdout`.
	Out io.Writer
	// OutputFlags defines the logging properties. See http://golang.org/pkg/log/#pkg-constants. To disable all flags, set this to `-1`. Defaults to log.LstdFlags (2009/01/23 01:23:23).
	OutputFlags int
	// IgnoredRequestURIs is a list of path values we do not want logged out. Exact match only!
	IgnoredRequestURIs []string
}

Options is a struct for specifying configuration parameters for the Logger middleware.