logging

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

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

 Go to latest Published: May 18, 2017 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.

Index

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.

Types

type Backend 

type Backend interface {
	Log(Level, int, *Record) error
	LogStr(Level, int, string) error
	GetFormatter() Formatter
}

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

func (b *LogBackend) GetFormatter() Formatter

func (*LogBackend) Log 

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

Log implements the Backend interface.

func (*LogBackend) LogStr 

func (b *LogBackend) LogStr(level Level, calldepth int, str string) 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
	Context        string
	// 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, capacity int) (*Logger, error)

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

func MustGetLogger 

func MustGetLogger(module, contextSeparator string, capacity int) *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) Print 

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

Print ...

func (*Logger) Printf 

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

Printf ...

func (*Logger) SetBackend 

func (l *Logger) SetBackend(backend Backend)

SetBackend overrides any previously defined backend for this logger.

func (*Logger) SetDumpBehavior 

func (l *Logger) SetDumpBehavior(enable bool, lvl Level, dumpPrefix string)

SetDumpBehavior ...

func (*Logger) SetFormatter 

func (l *Logger) SetFormatter(fmt Formatter)

SetFormatter ...

func (*Logger) SetLevel 

func (l *Logger) SetLevel(lvl Level)

SetLevel ...

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.

func (*Logger) WithContext 

func (l *Logger) WithContext(context string) *Logger

WithContext builds new logger with new ring buffer inside but with inherited context

func (*Logger) WithLevel 

func (l *Logger) WithLevel(level Level) *Logger

WithLevel ...

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(network, addr string, 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(network, addr string, 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) GetFormatter 

func (b *SyslogBackend) GetFormatter() Formatter

func (*SyslogBackend) Log 

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

Log implements the Backend interface.

func (*SyslogBackend) LogStr 

func (b *SyslogBackend) LogStr(level Level, calldepth int, str string) 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.