logging

package module
v0.0.0-...-7425251 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 9, 2021 License: BSD-3-Clause Imports: 17 Imported by: 0

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.

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

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 (
	FATAL Level = iota
	ERROR
	WARN
	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 FATAL as log level.

func (*Logger) Criticalf 

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

Criticalf logs a message using FATAL 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 WARN as log level.

func (*Logger) Warningf 

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

Warningf logs a message using WARN 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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.