README

Golang logging library

godoc build

Package logging implements a logging infrastructure for Go. Its output format is customizable and supports different logging backends like syslog, file and memory. Multiple backends can be utilized with different log levels per backend and logger.

NOTE: backwards compatibility promise have been dropped for master. Please vendor this package or use gopkg.in/op/go-logging.v1 for previous version. See changelog for details.

Example

Let's have a look at an example which demonstrates most of the features found in this library.

Example Output

package main

import (
	"os"

	"github.com/op/go-logging"
)

var log = logging.MustGetLogger("example")

// Example format string. Everything except the message has a custom color
// which is dependent on the log level. Many fields have a custom output
// formatting too, eg. the time returns the hour down to the milli second.
var format = logging.MustStringFormatter(
	`%{color}%{time:15:04:05.000} %{shortfunc} ▶ %{level:.4s} %{id:03x}%{color:reset} %{message}`,
)

// Password is just an example type implementing the Redactor interface. Any
// time this is logged, the Redacted() function will be called.
type Password string

func (p Password) Redacted() interface{} {
	return logging.Redact(string(p))
}

func main() {
	// For demo purposes, create two backend for os.Stderr.
	backend1 := logging.NewLogBackend(os.Stderr, "", 0)
	backend2 := logging.NewLogBackend(os.Stderr, "", 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.
	backend2Formatter := logging.NewBackendFormatter(backend2, format)

	// Only errors and more severe messages should be sent to backend1
	backend1Leveled := logging.AddModuleLevel(backend1)
	backend1Leveled.SetLevel(logging.ERROR, "")

	// Set the backends to be used.
	logging.SetBackend(backend1Leveled, backend2Formatter)

	log.Debugf("debug %s", Password("secret"))
	log.Info("info")
	log.Notice("notice")
	log.Warning("warning")
	log.Error("err")
	log.Critical("crit")
}

Installing

Using go get

$ go get github.com/op/go-logging

After this command go-logging is ready to use. Its source will be in:

$GOPATH/src/pkg/github.com/op/go-logging

You can use go get -u to update the package.

Documentation

For docs, see http://godoc.org/github.com/op/go-logging or run:

$ godoc github.com/op/go-logging

Additional resources

  • wslog -- exposes log messages through a WebSocket.
Expand ▾ Collapse ▴

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
    Output:
    
    debug arg
    error
    00:00:00.000 Example E error
    

    Index

    Examples

    Constants

    View Source
    const (
    	ColorBlack = iota + 30
    	ColorRed
    	ColorGreen
    	ColorYellow
    	ColorBlue
    	ColorMagenta
    	ColorCyan
    	ColorWhite
    )

    Variables

    View Source
    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}")
    )
    View Source
    var ErrInvalidLogLevel = errors.New("logger: invalid log level")

      ErrInvalidLogLevel is used when an invalid log level has been used.

      Functions

      func ColorSeq

      func ColorSeq(color color) string

      func ColorSeqBold

      func ColorSeqBold(color color) string

      func ConvertColors

      func ConvertColors(colors []int, bold bool) []string

        ConvertColors takes a list of ints representing colors for log levels and converts them into strings for ANSI color formatting

        func Redact

        func Redact(s string) string

          Redact returns a string of * having the same length as s.

          func Reset

          func Reset()

            Reset restores the internal state of the logging library.

            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.

              func SetLevel

              func SetLevel(level Level, module string)

                SetLevel sets the logging level for the specified module. The module corresponds to the string specified in GetLogger.

                Types

                type Backend

                type Backend interface {
                	Log(Level, int, *Record) error
                }

                  Backend is the interface which a log backend need to implement to be able to be used as a logging backend.

                  func NewBackendFormatter

                  func NewBackendFormatter(b Backend, f Formatter) Backend

                    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

                                  type Formatter interface {
                                  	Format(calldepth int, r *Record, w io.Writer) error
                                  }

                                    Formatter is the required interface for a custom log record formatter.

                                    func MustStringFormatter

                                    func MustStringFormatter(format string) Formatter

                                      MustStringFormatter is equivalent to NewStringFormatter with a call to panic on error.

                                      func NewStringFormatter

                                      func NewStringFormatter(format string) (Formatter, error)

                                        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 ~. meaning truncated path
                                        %{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.

                                        For the 'callpath' verb, the output can be adjusted to limit the printing the stack depth. i.e. '%{callpath:3}' will print '~.a.b.c'

                                        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.

                                          const (
                                          	CRITICAL Level = iota
                                          	ERROR
                                          	WARNING
                                          	NOTICE
                                          	INFO
                                          	DEBUG
                                          )

                                            Log levels.

                                            func GetLevel

                                            func GetLevel(module string) Level

                                              GetLevel returns the logging level for the specified module.

                                              func LogLevel

                                              func LogLevel(level string) (Level, error)

                                                LogLevel returns the log level from a string representation.

                                                func (Level) String

                                                func (p Level) String() string

                                                  String returns the string representation of a logging level.

                                                  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

                                                    type LeveledBackend interface {
                                                    	Backend
                                                    	Leveled
                                                    }

                                                      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

                                                            type LogBackend struct {
                                                            	Logger      *log.Logger
                                                            	Color       bool
                                                            	ColorConfig []string
                                                            }

                                                              LogBackend utilizes the standard log module.

                                                              func NewLogBackend

                                                              func NewLogBackend(out io.Writer, prefix string, flag int) *LogBackend

                                                                NewLogBackend creates a new LogBackend.

                                                                func (*LogBackend) Log

                                                                func (b *LogBackend) Log(level Level, calldepth int, rec *Record) error

                                                                  Log implements the Backend interface.

                                                                  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 GetLogger

                                                                    func GetLogger(module string) (*Logger, error)

                                                                      GetLogger creates and returns a Logger object based on the module name.

                                                                      func MustGetLogger

                                                                      func MustGetLogger(module string) *Logger

                                                                        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) Critical

                                                                        func (l *Logger) Critical(args ...interface{})

                                                                          Critical logs a message using CRITICAL as log level.

                                                                          func (*Logger) Criticalf

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

                                                                            Criticalf logs a message using CRITICAL as log level.

                                                                            func (*Logger) Debug

                                                                            func (l *Logger) Debug(args ...interface{})

                                                                              Debug logs a message using DEBUG as log level.

                                                                              func (*Logger) Debugf

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

                                                                                Debugf logs a message using DEBUG as log level.

                                                                                func (*Logger) Error

                                                                                func (l *Logger) Error(args ...interface{})

                                                                                  Error logs a message using ERROR as log level.

                                                                                  func (*Logger) Errorf

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

                                                                                    Errorf logs a message using ERROR as log level.

                                                                                    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) Fatalf

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

                                                                                        Fatalf is equivalent to l.Critical followed by a call to os.Exit(1).

                                                                                        func (*Logger) Info

                                                                                        func (l *Logger) Info(args ...interface{})

                                                                                          Info logs a message using INFO as log level.

                                                                                          func (*Logger) Infof

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

                                                                                            Infof logs a message using INFO as log level.

                                                                                            func (*Logger) IsEnabledFor

                                                                                            func (l *Logger) IsEnabledFor(level Level) bool

                                                                                              IsEnabledFor returns true if the logger is enabled for the given level.

                                                                                              func (*Logger) Notice

                                                                                              func (l *Logger) Notice(args ...interface{})

                                                                                                Notice logs a message using NOTICE as log level.

                                                                                                func (*Logger) Noticef

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

                                                                                                  Noticef logs a message using NOTICE as log 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) Panicf

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

                                                                                                      Panicf is equivalent to l.Critical followed by a call to panic().

                                                                                                      func (*Logger) SetBackend

                                                                                                      func (l *Logger) SetBackend(backend LeveledBackend)

                                                                                                        SetBackend overrides any previously defined backend for this logger.

                                                                                                        func (*Logger) Warning

                                                                                                        func (l *Logger) Warning(args ...interface{})

                                                                                                          Warning logs a message using WARNING as log level.

                                                                                                          func (*Logger) Warningf

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

                                                                                                            Warningf logs a message using WARNING as log level.

                                                                                                            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.

                                                                                                                    func (*MemoryBackend) Log

                                                                                                                    func (b *MemoryBackend) Log(level Level, calldepth int, rec *Record) error

                                                                                                                      Log implements the Log method required by Backend.

                                                                                                                      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.

                                                                                                                        func (*Record) Formatted

                                                                                                                        func (r *Record) Formatted(calldepth int) string

                                                                                                                          Formatted returns the formatted log record string.

                                                                                                                          func (*Record) Message

                                                                                                                          func (r *Record) Message() string

                                                                                                                            Message returns the log record message.

                                                                                                                            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

                                                                                                                              type SyslogBackend struct {
                                                                                                                              	Writer *syslog.Writer
                                                                                                                              }

                                                                                                                                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.

                                                                                                                                    func (*SyslogBackend) Log

                                                                                                                                    func (b *SyslogBackend) Log(level Level, calldepth int, rec *Record) error

                                                                                                                                      Log implements the Backend interface.

                                                                                                                                      Directories

                                                                                                                                      Path Synopsis