log

Documentation

Overview

Package log implements a minimalistic logging library.

Index

• Variables
• func Debugf(format string, val ...interface{})
• func Debugln(val ...interface{})
• func Printf(format string, val ...interface{})
• func Println(val ...interface{})
• type LogFormatter
• type Logger
  • func (l Logger) DebugMsg(kind string, fields ...interface{})
  • func (l Logger) DebugWriter() io.Writer
  • func (l Logger) Debugf(format string, val ...interface{})
  • func (l Logger) Debugln(val ...interface{})
  • func (l Logger) Error(msg string, err error, fields ...interface{})
  • func (l Logger) Msg(msg string, fields ...interface{})
  • func (l Logger) Printf(format string, val ...interface{})
  • func (l Logger) Println(val ...interface{})
  • func (l Logger) Write(s []byte) (int, error)
• type NopOutput
  • func (NopOutput) Close() error
  • func (NopOutput) Write(time.Time, bool, string)
• type Output
  • func FuncOutput(f func(time.Time, bool, string), close func() error) Output
  • func MultiOutput(outputs ...Output) Output
  • func SyslogOutput() (Output, error)
  • func WriteCloserOutput(wc io.WriteCloser, timestamps bool) Output
  • func WriterOutput(w io.Writer, timestamps bool) Output

Variables

var DefaultLogger = Logger{Out: WriterOutput(os.Stderr, false)}

DefaultLogger is the global Logger object that is used by package-level logging functions.

As with all other Loggers, it is not gorountine-safe on its own, however underlying log.Output may provide necessary serialization.

Functions

func Debugf

func Debugf(format string, val ...interface{})

func Debugln

func Debugln(val ...interface{})

func Printf

func Printf(format string, val ...interface{})

func Println

func Println(val ...interface{})

Types

type LogFormatter

type LogFormatter interface {
	FormatLog() string
}

type Logger

type Logger struct {
	Out   Output
	Name  string
	Debug bool

	// Additional fields that will be added
	// to the Msg output.
	Fields map[string]interface{}
}

Logger is the structure that writes formatted output to the underlying log.Output object.

Logger is stateless and can be copied freely. However, consider that underlying log.Output will not be copied.

Each log message is prefixed with logger name. Timestamp and debug flag formatting is done by log.Output.

No serialization is provided by Logger, its log.Output responsibility to ensure goroutine-safety if necessary.

func (Logger) DebugMsg

func (l Logger) DebugMsg(kind string, fields ...interface{})

func (Logger) DebugWriter

func (l Logger) DebugWriter() io.Writer

DebugWriter returns a writer that will act like Logger.Write but will use debug flag on messages. If Logger.Debug is false, Write method of returned object will be no-op.

func (Logger) Debugf

func (l Logger) Debugf(format string, val ...interface{})

func (Logger) Debugln

func (l Logger) Debugln(val ...interface{})

func (Logger) Error

func (l Logger) Error(msg string, err error, fields ...interface{})

Error writes an event log message in a machine-readable format (currently JSON) containing information about the error. If err does have a Fields method that returns map[string]interface{}, its result will be added to the message.

name: msg\t{"key":"value","key2":"value2"}

Additionally, values from fields will be added to it, as handled by Logger.Msg.

In the context of Error method, "msg" typically indicates the top-level context in which the error is *handled*. For example, if error leads to rejection of SMTP DATA command, msg will probably be "DATA error".

func (Logger) Msg

func (l Logger) Msg(msg string, fields ...interface{})

Msg writes an event log message in a machine-readable format (currently JSON).

name: msg\t{"key":"value","key2":"value2"}

Key-value pairs are built from fields slice which should contain key strings followed by corresponding values. That is, for example, []interface{"key", "value", "key2", "value2"}.

If value in fields implements LogFormatter, it will be represented by the string returned by FormatLog method. Same goes for fmt.Stringer and error interfaces.

Additionally, time.Time is written as a string in ISO 8601 format. time.Duration follows fmt.Stringer rule above.

func (Logger) Printf

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

func (Logger) Println

func (l Logger) Println(val ...interface{})

func (Logger) Write

func (l Logger) Write(s []byte) (int, error)

Write implements io.Writer, all bytes sent to it will be written as a separate log messages. No line-buffering is done.

type NopOutput

type NopOutput struct{}

func (NopOutput) Close

func (NopOutput) Close() error

func (NopOutput) Write

func (NopOutput) Write(time.Time, bool, string)

type Output

type Output interface {
	Write(stamp time.Time, debug bool, msg string)
	Close() error
}

func FuncOutput

func FuncOutput(f func(time.Time, bool, string), close func() error) Output

func MultiOutput

func MultiOutput(outputs ...Output) Output

func SyslogOutput

func SyslogOutput() (Output, error)

SyslogOutput returns a log.Output implementation that will send messages to the system syslog daemon.

Regular messages will be written with INFO priority, debug messages will be written with DEBUG priority.

Returned log.Output object is goroutine-safe.

func WriteCloserOutput

func WriteCloserOutput(wc io.WriteCloser, timestamps bool) Output

WriteCloserOutput returns a log.Output implementation that will write formatted messages to the provided io.Writer.

Closing returned log.Output object will close the underlying io.WriteCloser.

Written messages will include timestamp formatted with millisecond precision and [debug] prefix for debug messages. If timestamps argument is false, timestamps will not be added.

Returned log.Output does not provide its own serialization so goroutine-safety depends on the io.Writer. Most operating systems have atomic (read: thread-safe) implementations for stream I/O, so it should be safe to use WriterOutput with os.File.

func WriterOutput

func WriterOutput(w io.Writer, timestamps bool) Output

WriterOutput returns a log.Output implementation that will write formatted messages to the provided io.Writer.

Closing returned log.Output object will have no effect on the underlying io.Writer.

Written messages will include timestamp formatted with millisecond precision and [debug] prefix for debug messages. If timestamps argument is false, timestamps will not be added.

Returned log.Output does not provide its own serialization so goroutine-safety depends on the io.Writer. Most operating systems have atomic (read: thread-safe) implementations for stream I/O, so it should be safe to use WriterOutput with os.File.