httplog

README

go-httplog

A logger that has built in support for HTTP's 4xx client errors and 5xx server errors.

An interesting feature of this is that it can send the previous log message with the HTTP response (as HTTP headers). This is useful for debugging purposes.

Documention

Online documentation, which includes examples, can be found at: http://godoc.org/github.com/reiver/go-httplog

Documentation

Overview

Package httplog provides logging functionality that is more geared towards existing inside of an HTTP handler.

It provides 9 methods that you likely expect from a logger, which are exactly the same the ones in Go's built-in "log" package. Namely: Fatal, Fatalf, Fatalln, Panic, Panicf, Panicln, Print, Printf and Println.

So, for example, you are still able to do things such as:

func (handler *internalHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {

	httplogger := httplog.New(io.Writer, true)

	httplog.Print("ServeHTTP() BEGIN")

	// ...

	httplog.Print("ServeHTTP() END")
}

Which should be very familiar to anyone who has used Go's built in "log" package.

However, httplog also provides 26 methods (that Go's built-in "log" package does NOT have) that makes it easier to return a 2xx, 4xx or 5xx HTTP response.

So, for example, you are able to do things such as:

func (handler *internalHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {

	httplogger := httplog.New(io.Writer, true)

	// ...

	if nil != err {
		httplogger.Printf("Received an error: %v", err)
		httplogger.InternalServerError(w)
		return
	}

	// ...
}

The usage of the InternalServerError method in this example (as well as any of the other 25 of the 26 methods that make it easier to return a 2xx, 4xx or 5xx HTTP response) will completely deal with sending the HTTP response over the 'http.ResponseWriter'.

The other important feature is that if the 'http logger' was created with its 'dumpLogs' parameters set to 'true'. So, for example:

httplogger := httplog.New(os.Stdout, true)

Then in the header of the HTTP response sent with any of the 26 methods (that make it easier to return a 2xx, 4xx or 5xx HTTP response), such as InternalServerError, NotFound, Unauthorized, NotImplemented, etc, you will get the logs dumped using HTTP response headers that look like:

X-Log.000: ServeHTTP() BEGIN
X-Log.001: ServeHTTP() Received, subject = "This weekend?"
X-Log.002: ServeHTTP() Received, body    = "Hey,\nLet's go to White Pine this weekend. Ok?"
X-Log.003: ServeHTTP() Received, to      = ""
X-Log.004: ServeHTTP() user_id = 5
X-Log.005: ServeHTTP() Client Error: "to" is empty but is NOT allowed to be.

Or, for a better example of these headers, what it would look like with other HTTP response headers is:

Content-Type: application/json
Date: Wed, 15 Jul 2015 07:47:03 GMT
Expires: Thu, 19 Nov 1981 08:52:00 GMT
X-Log.000: ServeHTTP() BEGIN
X-Log.001: ServeHTTP() Received, subject = "This weekend?"
X-Log.002: ServeHTTP() Received, body    = "Hey,\nLet's go to White Pine this weekend. Ok?"
X-Log.003: ServeHTTP() Received, to      = ""
X-Log.004: ServeHTTP() user_id = 5
X-Log.005: ServeHTTP() Client Error: "to" is empty but is NOT allowed to be.

Index

• Constants
• type HttpLogger
  • func New(writer io.Writer, dumpLogs bool) HttpLogger
  • func Wrap(logger Logger, dumpLogs bool) HttpLogger
• type Logger

Constants

const (
	StatusNameOK = "OK" // 200

	StatusNameBadRequest                   = "Bad Request"
	StatusNameUnauthorized                 = "Unauthorized"
	StatusNamePaymentRequired              = "Payment Required"
	StatusNameForbidden                    = "Forbidden"
	StatusNameNotFound                     = "Not Found"
	StatusNameMethodNotAllowed             = "Method Not Allowed"
	StatusNameNotAcceptable                = "Not Acceptable"
	StatusNameProxyAuthRequired            = "Proxy Auth Required"
	StatusNameRequestTimeout               = "Request Timeout"
	StatusNameConflict                     = "Conflict"
	StatusNameGone                         = "Gone"
	StatusNameLengthRequired               = "Length Required"
	StatusNamePreconditionFailed           = "Precondition Failed"
	StatusNameRequestEntityTooLarge        = "Request Entity Too Large"
	StatusNameRequestURITooLong            = "Request URI Too Long"
	StatusNameUnsupportedMediaType         = "Unsupported Media Type"
	StatusNameRequestedRangeNotSatisfiable = "Requested RangeN ot Satisfiable"
	StatusNameExpectationFailed            = "Expectation Failed"
	StatusNameTeapot                       = "Teapot"

	StatusNameInternalServerError     = "Internal Server Error"
	StatusNameNotImplemented          = "Not Implemented"
	StatusNameBadGateway              = "Bad Gateway"
	StatusNameServiceUnavailable      = "Service Unavailable"
	StatusNameGatewayTimeout          = "Gateway Timeout"
	StatusNameHTTPVersionNotSupported = "HTTP Version Not Supported"
)

Types

type HttpLogger

type HttpLogger interface {
	Debug(...interface{})
	Debugf(string, ...interface{})
	Debugln(...interface{})

	Error(...interface{})
	Errorf(string, ...interface{})
	Errorln(...interface{})

	Fatal(...interface{})
	Fatalf(string, ...interface{})
	Fatalln(...interface{})

	Panic(...interface{})
	Panicf(string, ...interface{})
	Panicln(...interface{})

	Print(...interface{})
	Printf(string, ...interface{})
	Println(...interface{})

	Trace(...interface{})
	Tracef(string, ...interface{})
	Traceln(...interface{})

	Warn(...interface{})
	Warnf(string, ...interface{})
	Warnln(...interface{})

	OK(http.ResponseWriter, ...interface{})

	BadRequest(http.ResponseWriter, ...interface{})
	Unauthorized(http.ResponseWriter, ...interface{})
	PaymentRequired(http.ResponseWriter, ...interface{})
	Forbidden(http.ResponseWriter, ...interface{})
	NotFound(http.ResponseWriter, ...interface{})
	MethodNotAllowed(http.ResponseWriter, ...interface{})
	NotAcceptable(http.ResponseWriter, ...interface{})
	ProxyAuthRequired(http.ResponseWriter, ...interface{})
	RequestTimeout(http.ResponseWriter, ...interface{})
	Conflict(http.ResponseWriter, ...interface{})
	Gone(http.ResponseWriter, ...interface{})
	LengthRequired(http.ResponseWriter, ...interface{})
	PreconditionFailed(http.ResponseWriter, ...interface{})
	RequestEntityTooLarge(http.ResponseWriter, ...interface{})
	RequestURITooLong(http.ResponseWriter, ...interface{})
	UnsupportedMediaType(http.ResponseWriter, ...interface{})
	RequestedRangeNotSatisfiable(http.ResponseWriter, ...interface{})
	ExpectationFailed(http.ResponseWriter, ...interface{})
	Teapot(http.ResponseWriter, ...interface{})

	InternalServerError(http.ResponseWriter, ...interface{})
	NotImplemented(http.ResponseWriter, ...interface{})
	BadGateway(http.ResponseWriter, ...interface{})
	ServiceUnavailable(http.ResponseWriter, ...interface{})
	GatewayTimeout(http.ResponseWriter, ...interface{})
	HTTPVersionNotSupported(http.ResponseWriter, ...interface{})
}

HttpLogger is the interface that represents what an 'http logger' looks like.

The New func returns an HttpLogger interface (rather than the underlying struct).

The HttpLogger interface includes 9 methods that are exactly the same as Go's built-in "log" library. Namely: Fatal, Fatalf, Fatalln, Panic, Panicf, Panicln, Print, Printf and Println.

The HttpLogger interface also includes 26 methods (that the Go's built-in log library does NOT have) that makes it easier to return an 2xx, 4xx or 5xx HTTP response.

For example, a "404 Not Found" corresponds to the NotFound method, a "500 Internal Server Error" corresponds to the InternalServerError method, and a "408 Request Timeout" corresponds to the RequestTimeout. Etc.

func New

func New(writer io.Writer, dumpLogs bool) HttpLogger

New creates a new 'http logger'.

New takes 2 parameters: 'writer' and 'dumpLogs',

The 'writer' parameter tells New where the logs should be written to, as part of its normal logging operations.

The 'dumpLogs' parameter tells New whether the 26 methods for generating 2xx, 4xx and 5xx HTTP responses should dump the (past) logs that the 'http logger' has seen.

One would NOT want to dump these log in a 'production' deployment environment. And in that case 'dumpLogs' should be given a value of 'false'.

However, in a 'staging' or 'development' deployment environment one would indeed want to dump these logs (to make debugging easier). And in that case 'dumpLogs' should be given a value of 'true'.

func Wrap

func Wrap(logger Logger, dumpLogs bool) HttpLogger

type Logger

type Logger interface {
	Fatal(...interface{})
	Fatalf(string, ...interface{})
	Fatalln(...interface{})

	Panic(...interface{})
	Panicf(string, ...interface{})
	Panicln(...interface{})

	Print(...interface{})
	Printf(string, ...interface{})
	Println(...interface{})
}

Logger is the interface that represents what an 'logger' looks like.

The Wrap func takes one of these as an argument.

The Logger interface includes 9 methods that are exactly the same as Go's built-in "log" library. Namely: Fatal, Fatalf, Fatalln, Panic, Panicf, Panicln, Print, Printf and Println.