logger

Documentation

Overview

Package logger implements a configurable access logger.

The access log format is defined through a format string which expands to a log line per request. The values are taken as is and no quoting or escaping takes place. Text between two fields is printed verbatim. See the common log file formats for an example.

$header.<name>           - request http header (name: [a-zA-Z0-9-]+)
$remote_addr             - host:port of remote client
$remote_host             - host of remote client
$remote_port             - port of remote client
$request                 - request <method> <uri> <proto>
$request_args            - request query parameters
$request_host            - request host header (aka server name)
$request_method          - request method
$request_scheme          - request scheme
$request_uri             - request URI
$request_url             - request URL
$request_proto           - request protocol
$response_body_size      - response body size in bytes
$response_status         - response status code
$response_time_ms        - response time in S.sss format
$response_time_us        - response time in S.ssssss format
$response_time_ns        - response time in S.sssssssss format
$time_rfc3339            - log timestamp in YYYY-MM-DDTHH:MM:SSZ format
$time_rfc3339_ms         - log timestamp in YYYY-MM-DDTHH:MM:SS.sssZ format
$time_rfc3339_us         - log timestamp in YYYY-MM-DDTHH:MM:SS.ssssssZ format
$time_rfc3339_ns         - log timestamp in YYYY-MM-DDTHH:MM:SS.sssssssssZ format
$time_unix_ms            - log timestamp in unix epoch ms
$time_unix_us            - log timestamp in unix epoch us
$time_unix_ns            - log timestamp in unix epoch ns
$time_common             - log timestamp in DD/MMM/YYYY:HH:MM:SS -ZZZZ
$upstream_addr           - host:port of upstream server
$upstream_host           - host of upstream server
$upstream_port           - port of upstream server
$upstream_request_scheme - upstream request scheme
$upstream_request_uri    - upstream request URI
$upstream_request_url    - upstream request URL

Index

• Constants
• Variables
• type Event
• type LevelWriter
  • func NewLevelWriter(w io.Writer, level, prefix string) *LevelWriter
  • func (w *LevelWriter) Level() string
  • func (w *LevelWriter) SetLevel(s string) bool
  • func (w *LevelWriter) Write(b []byte) (int, error)
• type Logger
  • func New(w io.Writer, format string) (Logger, error)

Constants

const (
	CommonFormat   = `$remote_host - - [$time_common] "$request" $response_status $response_body_size`
	CombinedFormat = `$remote_host - - [$time_common] "$request" $response_status $response_body_size "$header.Referer" "$header.User-Agent"`
)

Common log file formats.

Variables

var Fields []string

Fields contains a list of all known static log fields in alphabetical order.

Types

type Event

type Event struct {
	// Start is the time when the action that triggered the event started.
	Start time.Time

	// End is the time when the action that triggered the event was completed.
	End time.Time

	// Request is the HTTP request that is connected to this event.
	// It should only be set for HTTP log events.
	Request *http.Request

	// Response is the HTTP response which is connected to this event.
	// It should only be set for HTTP log events.
	Response *http.Response

	// RequestURL is the URL of the incoming HTTP request.
	// It should only be set for HTTP log events.
	RequestURL *url.URL

	// UpstreamAddr is the TCP address in the form of "host:port" of the
	// upstream server which handled the proxied request.
	UpstreamAddr string

	// UpstreamService is the name of the upstream service as
	// defined in the route.
	UpstreamService string

	// UpstreamURL is the URL which was sent to the upstream server.
	// It should only be set for HTTP log events.
	UpstreamURL *url.URL
}

Event defines the elements of a loggable event.

type LevelWriter

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

LevelWriter implements a simplistic levelled log writer which supports TRACE, DEBUG, INFO, WARN, ERROR and FATAL. The log level can be changed at runtime.

func NewLevelWriter

func NewLevelWriter(w io.Writer, level, prefix string) *LevelWriter

NewLevelWriter creates a new leveled writer for the given output and a default level. Prefix is the string that is expected before the opening bracket and usually depends on the chosen log format. For the default log format prefix should be set to "2017/01/01 00:00:00 " whereby only the format and the spaces are relevant but not the date and time itself.

func (*LevelWriter) Level

func (w *LevelWriter) Level() string

Level returns the current log level.

func (*LevelWriter) SetLevel

func (w *LevelWriter) SetLevel(s string) bool

SetLevel sets the log level to the new value and returns true if that was successful.

func (*LevelWriter) Write

func (w *LevelWriter) Write(b []byte) (int, error)

type Logger

type Logger interface {
	Log(*Event)
}

Logger logs an event.

func New

func New(w io.Writer, format string) (Logger, error)

New creates a new logger that writes log events in the given format to the provided writer. If no writer was provided no log output is generated. If the format is empty or invalid an error is returned.