log

Documentation

Overview

Package log provides a structured, levelled logger interface for use in server handlers, which handles multiple output streams. A typical use might be to log everything to stderr, but to add another logger to send important data off to The Default logger simply logs to stderr, a local File logger is available, and data can be extracted and sent elsewhere by additional loggers (for example page hits to a stats service).

Usage: logger,err := log.NewStdErr() log.Add(logger) log.Error(log.V{"key":value,"key":value})

Index

• Constants
• Variables
• func Add(l StructuredLogger)
• func Debug(values map[string]interface{})
• func Error(values map[string]interface{})
• func Fatal(values map[string]interface{})
• func Info(values map[string]interface{})
• func Log(values map[string]interface{})
• func Middleware(h http.HandlerFunc) http.HandlerFunc
• func SetRequestID(r *http.Request, rid *RequestID) *http.Request
• func Time(start time.Time, values map[string]interface{})
• func Trace(r *http.Request) string
• type Default
  • func NewStdErr(prefix string) (*Default, error)
  • func (d *Default) LevelColor(l int) string
  • func (d *Default) LevelName(l int) string
  • func (d *Default) LevelValue(values V) int
  • func (d *Default) Log(values V)
  • func (d *Default) SortedKeys(values V) []string
  • func (d *Default) WriteString(s string)
• type File
  • func NewFile(path string) (*File, error)
• type Logger
  • func New(path string, production bool) *Logger
  • func (l *Logger) Printf(format string, args ...interface{})
• type RequestID
  • func GetRequestID(r *http.Request) *RequestID
  • func (r *RequestID) String() string
• type StructuredLogger
• type V
• type Values

Constants

const (
	// Separator is used to separate key:value pairs
	Separator = ":"
	// PrefixDate constant for date prefixes
	PrefixDate = "2006-01-02 "
	// PrefixTime  constants for time prefix
	PrefixTime = "15:04:05 "
	// PrefixDateTime  constants for date + time prefix
	PrefixDateTime = "2006-01-02:15:04:05 "
)

const (
	// FileFlags serts the flags for OpenFile on the log file
	FileFlags = os.O_WRONLY | os.O_APPEND | os.O_CREATE

	// FilePermissions serts the perms for OpenFile on the log file
	FilePermissions = 0640
)

const (
	// LevelKey is the key for setting level
	LevelKey = "level"
	// MessageKey is the key for a message
	MessageKey = "msg"
	// DurationKey is used by the Time function
	DurationKey = "duration"
	// ErrorKey is used for errors
	ErrorKey = "error"
	// IPKey is used for IP addresses (for colouring)
	IPKey = "ip"
	// URLKey is used for identifying URLs (for filtering)
	URLKey = "url"
	// TraceKey is used for trace ids emitted in middleware
	TraceKey = "trace"
)

const (
	LevelNone = iota
	LevelDebug
	LevelInfo
	LevelError
	LevelFatal
)

Valid levels for logging.

Variables

var (
	// LevelNames is a list of human-readable for levels.
	LevelNames = []string{"none", "debug", "info", "error", "fatal"}

	// NoColor determines if a terminal is colourable or not
	NoColor = os.Getenv("TERM") == "dumb"

	// LevelColors is a list of human-friendly terminal colors for levels.
	LevelColors = []string{"\033[0m", "\033[34m", "\033[32m", "\033[33m", "\033[31m"}

	// TraceColor sets a for IP addresses or request id
	TraceColor = "\033[33m"

	// ClearColors clears all formatting
	ClearColors = "\033[0m"
)

Functions

func Add

func Add(l StructuredLogger)

Add adds the given logger to the list of outputs, it should not be called from other goroutines.

func Debug

func Debug(values map[string]interface{})

Debug sends the key/value map at level Debug to all registered (log)gers.

func Error

func Error(values map[string]interface{})

Error sends the key/value map at level Error to all registered loggers.

func Fatal

func Fatal(values map[string]interface{})

Fatal sends the key/value map at level Fatal to all registered loggers, no other action is taken.

func Info

func Info(values map[string]interface{})

Info sends the key/value map at level Info to all registered loggers.

func Log

func Log(values map[string]interface{})

Log sends the key/value map to all registered loggers. If level is not set, it defaults to LevelInfo.

func Middleware

func Middleware(h http.HandlerFunc) http.HandlerFunc

Middleware adds a logging wrapper and request tracing to requests.

func SetRequestID

func SetRequestID(r *http.Request, rid *RequestID) *http.Request

SetRequestID saves the request id in the request context.

func Time

func Time(start time.Time, values map[string]interface{})

Time sends the key/value map to all registered loggers with an additional duration, start and end params set.

func Trace

func Trace(r *http.Request) string

Trace retreives the request id from a request as a string.

Types

type Default

type Default struct {

	// Prefix is used to prefix any log lines emitted.
	Prefix string

	// Level is the level above which input is ignored.
	Level int

	// Writer is the output of this logger.
	Writer io.Writer

	// Color sets whether terminal colour instructions are emitted.
	Color bool
}

Default defines a default logger which simply logs to Writer, Writer is set to stderr, Level is LevelDebug and Prefix is empty by default.

func NewStdErr

func NewStdErr(prefix string) (*Default, error)

NewStdErr returns a new StructuredLogger of type Default which writes to stderr. By default prefix is empty, and level is LevelDebug (the lowest), so all output is captured.

func (*Default) LevelColor

func (d *Default) LevelColor(l int) string

LevelColor returns the human-readable colour for this level.

func (*Default) LevelName

func (d *Default) LevelName(l int) string

LevelName returns the human-readable name for this level.

func (*Default) LevelValue

func (d *Default) LevelValue(values V) int

LevelValue extracts the Level from values (if present) or returns 0 if not.

func (*Default) Log

func (d *Default) Log(values V)

Log logs the key:value pairs given to the writer. Keys are sorted before output in alphabetical order to ensure consistent results.

func (*Default) SortedKeys

func (d *Default) SortedKeys(values V) []string

SortedKeys returns an array of keys for a map sorted in alpha order, this means we get a predictable order for the map entries when we print. The special keys level and message are ommitted.

func (*Default) WriteString

func (d *Default) WriteString(s string)

WriteString writes the string to the Writer.

type File

type File struct {
	Default // File embeds default
	Path    string
}

File logs to a local file for all messages at or above Level.

func NewFile

func NewFile(path string) (*File, error)

NewFile creates a new file logger for the given path at Level Info.

type Logger

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

Logger conforms with the server.Logger interface

func New

func New(path string, production bool) *Logger

New creates a new Logger which writes to a file and to stderr

func (*Logger) Printf

func (l *Logger) Printf(format string, args ...interface{})

Printf logs events selectively given our filter

type RequestID

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

RequestID is but a simple token for tracing requests.

func GetRequestID

func GetRequestID(r *http.Request) *RequestID

GetRequestID retreives the request id from a request.

func (*RequestID) String

func (r *RequestID) String() string

String returns a string formatting for the request id.

type StructuredLogger

type StructuredLogger interface {
	Log(V)
}

StructuredLogger defines an interface for loggers which may be added with Add() to the list of outputs.

type V

type V map[string]interface{}

V is a shorthand for values

type Values

type Values map[string]interface{}

Values is a map of structured key value pairs usage: log.Warn(log.Values{"user":1,"foo":"bar"})