Documentation ¶
Overview ¶
Package logging implements a logging infrastructure for Go. It supports different logging backends like syslog, file and memory. Multiple backends can be utilized with different log levels per backend and logger.
Example ¶
// This call is for testing purposes and will set the time to unix epoch. InitForTesting(DEBUG) var log = MustGetLogger("example") // For demo purposes, create two backend for os.Stdout. // // os.Stderr should most likely be used in the real world but then the // "Output:" check in this example would not work. backend1 := NewLogBackend(os.Stdout, "", 0) backend2 := NewLogBackend(os.Stdout, "", 0) // For messages written to backend2 we want to add some additional // information to the output, including the used log level and the name of // the function. var format = MustStringFormatter( `%{time:15:04:05.000} %{shortfunc} %{level:.1s} %{message}`, ) backend2Formatter := NewBackendFormatter(backend2, format) // Only errors and more severe messages should be sent to backend2 backend2Leveled := AddModuleLevel(backend2Formatter) backend2Leveled.SetLevel(ERROR, "") // Set the backends to be used and the default level. SetBackend(backend1, backend2Leveled) log.Debugf("debug %s", "arg") log.Error("error")
Output: debug arg error 00:00:00.000 Example E error
Index ¶
- Constants
- Variables
- func ColorSeq(color color) string
- func ColorSeqBold(color color) string
- func ConvertColors(colors []int, bold bool) []string
- func Redact(s string) string
- func Reset()
- func SetFormatter(f Formatter)
- func SetLevel(level Level, module string)
- type Backend
- type ChannelMemoryBackend
- type Formatter
- type Level
- type Leveled
- type LeveledBackend
- type LogBackend
- type Logger
- func (l *Logger) Critical(format string, args ...interface{})
- func (l *Logger) Debug(format string, args ...interface{})
- func (l *Logger) Debugf(format string, args ...interface{})
- func (l *Logger) Error(format string, args ...interface{})
- func (l *Logger) Errorf(format string, args ...interface{})
- func (l *Logger) Fatal(args ...interface{})
- func (l *Logger) Fatalf(format string, args ...interface{})
- func (l *Logger) Info(format string, args ...interface{})
- func (l *Logger) Infof(format string, args ...interface{})
- func (l *Logger) IsEnabledFor(level Level) bool
- func (l *Logger) Notice(format string, args ...interface{})
- func (l *Logger) Noticef(format string, args ...interface{})
- func (l *Logger) Panic(args ...interface{})
- func (l *Logger) Panicf(format string, args ...interface{})
- func (l *Logger) SetBackend(backend LeveledBackend)
- func (l *Logger) Warning(format string, args ...interface{})
- func (l *Logger) Warningf(format string, args ...interface{})
- type MemoryBackend
- type Record
- type Redactor
- type SyslogBackend
Examples ¶
Constants ¶
const ( ColorBlack = iota + 30 ColorRed ColorGreen ColorYellow ColorBlue ColorMagenta ColorCyan ColorWhite )
Variables ¶
var ( // DefaultFormatter is the default formatter used and is only the message. DefaultFormatter = MustStringFormatter("%{message}") // GlogFormatter mimics the glog format GlogFormatter = MustStringFormatter("%{level:.1s}%{time:0102 15:04:05.999999} %{pid} %{shortfile}] %{message}") )
var ErrInvalidLogLevel = errors.New("logger: invalid log level")
ErrInvalidLogLevel is used when an invalid log level has been used.
Functions ¶
func ColorSeqBold ¶
func ColorSeqBold(color color) string
func ConvertColors ¶
ConvertColors takes a list of ints representing colors for log levels and converts them into strings for ANSI color formatting
func SetFormatter ¶
func SetFormatter(f Formatter)
SetFormatter sets the default formatter for all new backends. A backend will fetch this value once it is needed to format a record. Note that backends will cache the formatter after the first point. For now, make sure to set the formatter before logging.
Types ¶
type Backend ¶
Backend is the interface which a log backend need to implement to be able to be used as a logging backend.
func NewBackendFormatter ¶
NewBackendFormatter creates a new backend which makes all records that passes through it beeing formatted by the specific formatter.
type ChannelMemoryBackend ¶
type ChannelMemoryBackend struct {
// contains filtered or unexported fields
}
ChannelMemoryBackend is very similar to the MemoryBackend, except that it internally utilizes a channel.
func NewChannelMemoryBackend ¶
func NewChannelMemoryBackend(size int) *ChannelMemoryBackend
NewChannelMemoryBackend creates a simple in-memory logging backend which utilizes a go channel for communication.
Start will automatically be called by this function.
func (*ChannelMemoryBackend) Flush ¶
func (b *ChannelMemoryBackend) Flush()
Flush waits until all records in the buffered channel have been processed.
func (*ChannelMemoryBackend) Head ¶
func (b *ChannelMemoryBackend) Head() *node
Head returns the oldest record node kept in memory. It can be used to iterate over records, one by one, up to the last record.
Note: new records can get added while iterating. Hence the number of records iterated over might be larger than the maximum size.
func (*ChannelMemoryBackend) Log ¶
func (b *ChannelMemoryBackend) Log(level Level, calldepth int, rec *Record) error
Log implements the Log method required by Backend.
func (*ChannelMemoryBackend) Start ¶
func (b *ChannelMemoryBackend) Start()
Start launches the internal goroutine which starts processing data from the input channel.
func (*ChannelMemoryBackend) Stop ¶
func (b *ChannelMemoryBackend) Stop()
Stop signals the internal goroutine to exit and waits until it have.
type Formatter ¶
Formatter is the required interface for a custom log record formatter.
func MustStringFormatter ¶
MustStringFormatter is equivalent to NewStringFormatter with a call to panic on error.
func NewStringFormatter ¶
NewStringFormatter returns a new Formatter which outputs the log record as a string based on the 'verbs' specified in the format string.
The verbs:
General:
%{id} Sequence number for log message (uint64). %{pid} Process id (int) %{time} Time when log occurred (time.Time) %{level} Log level (Level) %{module} Module (string) %{program} Basename of os.Args[0] (string) %{message} Message (string) %{longfile} Full file name and line number: /a/b/c/d.go:23 %{shortfile} Final file name element and line number: d.go:23 %{callpath} Callpath like main.a.b.c...c "..." meaning recursive call %{color} ANSI color based on log level
For normal types, the output can be customized by using the 'verbs' defined in the fmt package, eg. '%{id:04d}' to make the id output be '%04d' as the format string.
For time.Time, use the same layout as time.Format to change the time format when output, eg "2006-01-02T15:04:05.999Z-07:00".
For the 'color' verb, the output can be adjusted to either use bold colors, i.e., '%{color:bold}' or to reset the ANSI attributes, i.e., '%{color:reset}' Note that if you use the color verb explicitly, be sure to reset it or else the color state will persist past your log message. e.g., "%{color:bold}%{time:15:04:05} %{level:-8s}%{color:reset} %{message}" will just colorize the time and level, leaving the message uncolored.
Colors on Windows is unfortunately not supported right now and is currently a no-op.
There's also a couple of experimental 'verbs'. These are exposed to get feedback and needs a bit of tinkering. Hence, they might change in the future.
Experimental:
%{longpkg} Full package path, eg. github.com/go-logging %{shortpkg} Base package path, eg. go-logging %{longfunc} Full function name, eg. littleEndian.PutUint32 %{shortfunc} Base function name, eg. PutUint32 %{callpath} Call function path, eg. main.a.b.c
type Level ¶
type Level int
Level defines all available log levels for log messages.
type Leveled ¶
type Leveled interface { GetLevel(string) Level SetLevel(Level, string) IsEnabledFor(Level, string) bool }
Leveled interface is the interface required to be able to add leveled logging.
type LeveledBackend ¶
LeveledBackend is a log backend with additional knobs for setting levels on individual modules to different levels.
func AddModuleLevel ¶
func AddModuleLevel(backend Backend) LeveledBackend
AddModuleLevel wraps a log backend with knobs to have different log levels for different modules.
func MultiLogger ¶
func MultiLogger(backends ...Backend) LeveledBackend
MultiLogger creates a logger which contain multiple loggers.
func SetBackend ¶
func SetBackend(backends ...Backend) LeveledBackend
SetBackend replaces the backend currently set with the given new logging backend.
type LogBackend ¶
LogBackend utilizes the standard log module.
func NewLogBackend ¶
func NewLogBackend(out io.Writer, prefix string, flag int) *LogBackend
NewLogBackend creates a new LogBackend.
type Logger ¶
type Logger struct { Module string // ExtraCallDepth can be used to add additional call depth when getting the // calling function. This is normally used when wrapping a logger. ExtraCalldepth int // contains filtered or unexported fields }
Logger is the actual logger which creates log records based on the functions called and passes them to the underlying logging backend.
func MustGetLogger ¶
MustGetLogger is like GetLogger but panics if the logger can't be created. It simplifies safe initialization of a global logger for eg. a package.
func (*Logger) Fatal ¶
func (l *Logger) Fatal(args ...interface{})
Fatal is equivalent to l.Critical(fmt.Sprint()) followed by a call to os.Exit(1).
func (*Logger) IsEnabledFor ¶
IsEnabledFor returns true if the logger is enabled for the given level.
func (*Logger) Panic ¶
func (l *Logger) Panic(args ...interface{})
Panic is equivalent to l.Critical(fmt.Sprint()) followed by a call to panic().
func (*Logger) SetBackend ¶
func (l *Logger) SetBackend(backend LeveledBackend)
SetBackend overrides any previously defined backend for this logger.
type MemoryBackend ¶
type MemoryBackend struct {
// contains filtered or unexported fields
}
MemoryBackend is a simple memory based logging backend that will not produce any output but merly keep records, up to the given size, in memory.
func InitForTesting ¶
func InitForTesting(level Level) *MemoryBackend
InitForTesting is a convenient method when using logging in a test. Once called, the time will be frozen to January 1, 1970 UTC.
func NewMemoryBackend ¶
func NewMemoryBackend(size int) *MemoryBackend
NewMemoryBackend creates a simple in-memory logging backend.
func (*MemoryBackend) Head ¶
func (b *MemoryBackend) Head() *node
Head returns the oldest record node kept in memory. It can be used to iterate over records, one by one, up to the last record.
Note: new records can get added while iterating. Hence the number of records iterated over might be larger than the maximum size.
type Record ¶
type Record struct { Id uint64 Time time.Time Module string Level Level Args []interface{} // contains filtered or unexported fields }
Record represents a log record and contains the timestamp when the record was created, an increasing id, filename and line and finally the actual formatted log line.
type Redactor ¶
type Redactor interface {
Redacted() interface{}
}
Redactor is an interface for types that may contain sensitive information (like passwords), which shouldn't be printed to the log. The idea was found in relog as part of the vitness project.
type SyslogBackend ¶
SyslogBackend is a simple logger to syslog backend. It automatically maps the internal log levels to appropriate syslog log levels.
func NewSyslogBackend ¶
func NewSyslogBackend(prefix string) (b *SyslogBackend, err error)
NewSyslogBackend connects to the syslog daemon using UNIX sockets with the given prefix. If prefix is not given, the prefix will be derived from the launched command.
func NewSyslogBackendPriority ¶
func NewSyslogBackendPriority(prefix string, priority syslog.Priority) (b *SyslogBackend, err error)
NewSyslogBackendPriority is the same as NewSyslogBackend, but with custom syslog priority, like syslog.LOG_LOCAL3|syslog.LOG_DEBUG etc.