httplog

README

go-httplog

Robust, smart logger for Golang http request/response.

It provides way to log in details every request and response with chosen fields. It requires any structured logger that fits under httplog.FieldLogger interface.

It comes with useful integration with logrus, but it can be extend to use any logger. It fits into standard net/http middleware (http.Handler) pattern, but comes also with echo integration.

It comes with bunch of configurable fields. Not exhausting list of these:

ReqTimeField  = RequestField("req_time")
IDField       = RequestField("req_id")
RemoteIPField = RequestField("req_remote_ip")
HostField     = RequestField("req_host")
URIField      = RequestField("req_uri")
ReqArgsField  = RequestField("req_args")
MethodField   = RequestField("req_method")
PathField     = RequestField("req_path")
BytesInField  = RequestField("req_bytes_in")
AuthField     = RequestField("req_auth_header")

StatusField       = ResponseField("res_status")
BytesOutField     = ResponseField("res_bytes_out")
ResTimeField      = ResponseField("res_time")
ContentTypeField  = ResponseField("res_content_type")
LocationField     = ResponseField("res_location")
LocationArgsField = ResponseField("res_location_args")
LocationHostField = ResponseField("res_location_host")

Example:

package main

import (
    "net/http"
    
    "github.com/Bplotka/go-httplog"
    "github.com/Bplotka/go-httplog/logrus"
    "github.com/sirupsen/logrus"
)

func main() {
    l := logrus.New()
    
    srv := http.Server{
        Handler: httplog.RegisterMiddleware(
            httplogrus.ToHTTPFieldLoggerDebug(l), // or ToHTTPFieldLoggerInfo if you want these logs to be in Info level.
            httplog.DefaultReqResConfig(), // or httplog.DefaultResponseOnlyConfig() for only log line per response. 
        )(
            http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                // Your handler here...
                l.Info("Inside!")
            }),
        ),
    }
    
    err := srv.Serve(...)
    if err != nil {
        // handle err.
    }
}

Example effect:

• With DefaultReqResConfig on any request you will get:

Debug[0029] Received HTTP request                         req_bytes_in=0 req_host="127.0.0.1:<some-port>" req_method=GET req_path="...." req_remote_ip=127.0.0.1 req_time="2017-04-14T17:20:07+01:00" <any other field that will filled and configured>
Inside!
Debug[0029] Responding to HTTP request                    res_bytes_out=769 res_content_type="application/json" res_status=200 res_time="2017-04-14T17:20:07+01:00" <any other field that will filled and configured>

For redirection the log can be even more useful:

Debug[0029] Received HTTP request                         req_bytes_in=0 req_host="127.0.0.1:<some-port>" req_method=GET req_path="...." req_remote_ip=127.0.0.1 req_time="2017-04-14T17:20:07+01:00" <any other field that will filled and configured>
Inside!
Debug[0029] Redirecting HTTP request                      res_bytes_out=0 res_location_args="code=...&state=..." res_location_host="...." res_status=303 res_time="2017-04-14T17:20:07+01:00" <any other field that will filled and configured>" 

Integrations:

Web frameworks

• net/http ;>
• echo

Structured Loggers

• logrus

Documentation

Index

• Constants
• Variables
• func RegisterMiddleware(logger FieldLogger, cfg Config) func(http.Handler) http.Handler
• type Config
  • func DefaultReqResConfig() Config
  • func DefaultResponseOnlyConfig() Config
• type FieldLogger
• type Fields
• type Logger
  • func New(logger FieldLogger, cfg Config) *Logger
  • func (l *Logger) RequestHandler() func(w http.ResponseWriter, r *http.Request)
  • func (l *Logger) WrapResponse(w http.ResponseWriter, r *http.Request) http.ResponseWriter
• type MockFieldLogger
  • func (_m *MockFieldLogger) Log(args ...interface{})
  • func (_m *MockFieldLogger) WithError(err error) FieldLogger
  • func (_m *MockFieldLogger) WithFields(fields Fields) FieldLogger
• type RequestField
• type ResponseField

Constants

const (
	// ReqTimeField contains time of request receiving.
	ReqTimeField = RequestField("req_time")
	// IDField contains ID of the request.
	IDField = RequestField("req_id")
	// RemoteIPField contains request remote IP.
	RemoteIPField = RequestField("req_remote_ip")
	// HostField contains request host.
	HostField = RequestField("req_host")
	// URIField contains full URI of the request.
	URIField = RequestField("req_uri")
	// CompactURIField contains request arguments which are compacted (only keys).
	CompactURIField = RequestField("req_uri_compact")
	// MethodField contains request method.
	MethodField = RequestField("req_method")
	// PathField contains path of request.
	PathField = RequestField("req_path")
	// BytesInField contains size of request in bytes.
	BytesInField = RequestField("req_bytes_in")
	// AuthField contains auth header for request.
	AuthField = RequestField("req_auth_header")
)

const (
	// StatusField contains status code.
	StatusField = ResponseField("res_status")
	// BytesOutField contains size of response in bytes.
	BytesOutField = ResponseField("res_bytes_out")
	// ResTimeField contains time returning response or redirecting.
	ResTimeField = ResponseField("res_time")
	// ContentTypeField contains content-type of the response.
	ContentTypeField = ResponseField("res_content_type")
	// LocationField contains full redirection URL in case of redirection response.
	LocationField = ResponseField("res_location")
	// LocationCompactArgsField contains arguments of redirection URL in case of redirection response in compacted form (only keys).
	LocationCompactArgsField = ResponseField("res_location_compact")
	// LocationHostField contains host of redirection URL in case of redirection response.
	LocationHostField = ResponseField("res_location_host")
)

Variables

var DefaultRequestFields = []RequestField{
	ReqTimeField,
	IDField,
	RemoteIPField,
	HostField,
	CompactURIField,
	MethodField,
	PathField,
	BytesInField,
	AuthField,
}

DefaultRequestFields is a list for recommended configuration of request fields.

var DefaultResponseFields = []ResponseField{
	StatusField,
	BytesOutField,
	ResTimeField,
	ContentTypeField,
	LocationCompactArgsField,
	LocationHostField,
}

DefaultResponseFields is a list for recommended configuration of response fields.

Functions

func RegisterMiddleware

func RegisterMiddleware(logger FieldLogger, cfg Config) func(http.Handler) http.Handler

RegisterMiddleware registers handler that will log request at the beginning and served response at the request end.

Types

type Config

type Config struct {
	// RequestFields specifies request fields that should be logged when request is received (before server handling).
	RequestFields []RequestField

	// ResponseFields specifies response fields that should be logged when response is returned/redirected
	// (right after server handling).
	ResponseFields []ResponseField
	// ResponseReqFields specifies request fields that should be logged when response is returned/redirected
	// (right after server handling). It is useful if you want to log only once per request. (common logging technique)
	ResponseReqFields []RequestField
}

Config is a configuration for httplog.

func DefaultReqResConfig

func DefaultReqResConfig() Config

DefaultReqResConfig is configuration for logging one entry when request is received and one when response is written.

func DefaultResponseOnlyConfig

func DefaultResponseOnlyConfig() Config

DefaultResponseOnlyConfig is configuration for logging only an entry when response is written.

type FieldLogger

type FieldLogger interface {
	WithFields(fields Fields) FieldLogger
	Log(args ...interface{})
}

The FieldLogger interface generalizes structured logging used by httplog.

type Fields

type Fields map[string]interface{}

Fields type, used to pass to `WithFields`.

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger is an instance for httplog to register middleware and wrap response.

func New

func New(logger FieldLogger, cfg Config) *Logger

New constructs new httplog Logger.

func (*Logger) RequestHandler

func (l *Logger) RequestHandler() func(w http.ResponseWriter, r *http.Request)

RequestHandler handles request log entry. Should be places at before serving response.

func (*Logger) WrapResponse

func (l *Logger) WrapResponse(w http.ResponseWriter, r *http.Request) http.ResponseWriter

WrapResponse wraps ResponseWriter. It is the only way to get details about response without including custom code in user handlers.

type MockFieldLogger

type MockFieldLogger struct {
	mock.Mock
}

MockFieldLogger is an autogenerated mock type for the FieldLogger type

func (*MockFieldLogger) Log

func (_m *MockFieldLogger) Log(args ...interface{})

Log provides a mock function with given fields: args

func (*MockFieldLogger) WithError

func (_m *MockFieldLogger) WithError(err error) FieldLogger

WithError provides a mock function with given fields: err

func (*MockFieldLogger) WithFields

func (_m *MockFieldLogger) WithFields(fields Fields) FieldLogger

WithFields provides a mock function with given fields: fields

type RequestField

type RequestField string

RequestField is a log field that can be deducted from http.Request.

type ResponseField

type ResponseField string

ResponseField is a log field that can be deducted from response. It is done by wrapping http.ResponseWriter.