logging

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

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

Go to latest
Published: Feb 12, 2016 License: BSD-3-Clause Imports: 16 Imported by: 0

README

Golang logging library

Build Status

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.

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:

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

You can use go get -u -a to update all installed packages.

Example

You can find a more detailed example at the end.

package main

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

var log = logging.MustGetLogger("package.example")

func main() {
	var format = logging.MustStringFormatter("%{level} %{message}")
	logging.SetFormatter(format)
	logging.SetLevel(logging.INFO, "package.example")

	log.Debug("hello %s", "golang")
	log.Info("hello %s", "golang")
}

Documentation

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

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

Full example

package main

import (
	stdlog "log"
	"os"

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

var log = logging.MustGetLogger("test")

type Password string

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

func main() {
	// Customize the output format
	logging.SetFormatter(logging.MustStringFormatter("▶ %{color}%{level:.1s}%{color:reset} 0x%{id:x} %{message}"))

	// Setup one stdout and one syslog backend.
	logBackend := logging.NewLogBackend(os.Stderr, "", stdlog.LstdFlags|stdlog.Lshortfile)
	logBackend.Color = true

	syslogBackend, err := logging.NewSyslogBackend("")
	if err != nil {
		log.Fatal(err)
	}

	// Combine them both into one logging backend.
	logging.SetBackend(logBackend, syslogBackend)

	// Run one with debug setup for "test" and one with error.
	for _, level := range []logging.Level{logging.DEBUG, logging.ERROR} {
		// note that SetLevel should be called _after_
                // configuring the backend, since these settings
                // actually get pushed into the backed
		logging.SetLevel(level, "test")

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

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

This section is empty.

Variables

View Source
var ErrInvalidLogLevel = errors.New("logger: invalid log level")

Functions

func AddBackend

func AddBackend(b Backend)

AddBackend adds a new backend to the backend chain

func MustStringFormatter

func MustStringFormatter(format string) *stringFormatter

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

func NewStringFormatter

func NewStringFormatter(format string) (*stringFormatter, error)

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. Glob characters suitable for use in `path.Match` may be used. Exact (non-glob) settings take precedence over pattern matches, and in the case of overlapping patterns, settings applied later override earlier settings

Types

type Annotater

type Annotater interface {
	Annotate(*Record)
}

type Annotation

type Annotation struct {
	Key   string
	Value interface{}
}

Annotation is a key/value entry; the Annotator backend can add annotations

type Annotator

type Annotator struct {
	Extras        map[string]Annotation
	DynamicExtras func() []Annotation
	// contains filtered or unexported fields
}

An Annotator is a kind of Backend that adds some annotations to a message in flight

func NewAnnotator

func NewAnnotator(b Backend) *Annotator

func (*Annotator) Add

func (a *Annotator) Add(key string, val interface{})

func (*Annotator) Backend

func (a *Annotator) Backend() Backend

func (*Annotator) Log

func (a *Annotator) Log(lvl Level, depth int, rec *Record) error

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.

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.

var (
	// DefaultFormatter is the default formatter used and is only the message.
	DefaultFormatter Formatter = MustStringFormatter("%{message}")

	// Glog format
	GlogFormatter Formatter = MustStringFormatter("%{level:.1s}%{time:0102 15:04:05.999999} %{pid} %{shortfile}] %{message}")
)

type Level

type Level int

Level defines all available log levels for log messages.

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

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 LevelLogger

type LevelLogger interface {
	// a logging.LevelLogger is also a standardlog.Logger
	Fatal(v ...interface{})
	Fatalf(format string, v ...interface{})
	Fatalln(v ...interface{})
	Panic(v ...interface{})
	Panicf(format string, v ...interface{})
	Panicln(v ...interface{})
	Print(v ...interface{})
	Printf(format string, v ...interface{})
	Println(v ...interface{})

	// Go1 details of log.Logger that don't seem appropriate to
	// the abstract notion of logging
	Output(calldepth int, s string) error
	Outputf(adjcalldepth int, format string, args ...interface{})
	Prefix() string
	Flags() int
	SetFlags(flag int)
	SetPrefix(prefix string)

	Debug(format string, args ...interface{})
	Info(format string, args ...interface{})
	Notice(format string, args ...interface{})
	Warning(format string, args ...interface{})
	Error(format string, args ...interface{})
	Critical(format string, args ...interface{})
}

type Leveled

type Leveled interface {
	GetLevel(string) Level
	SetLevel(Level, string)
	IsEnabledFor(Level, string) bool
}

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

Set backend replaces the backend currently set with the given new logging backend.

type LogBackend

type LogBackend struct {
	Logger *log.Logger
	Color  bool
}

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

type Logger

type Logger struct {
	Module string

	// the Level at which we Output records (defaults to INFO)
	OutputLevel Level
	// contains filtered or unexported fields
}

func GetLogger

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

TODO call NewLogger and remove MustGetLogger? 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) Backend

func (l *Logger) Backend() LeveledBackend

func (*Logger) Critical

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

Critical logs a message using CRITICAL as log level.

func (*Logger) Debug

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

Debug logs a message using DEBUG as log level.

func (*Logger) Error

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

Error 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) Fatalln

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

Fatalln is equivalent to l.Critical(fmt.Sprintln()) followed by a call to os.Exit(1).

func (*Logger) Flags

func (l *Logger) Flags() int

func (*Logger) Info

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

Info 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) Log

func (l *Logger) Log(lvl Level, format string, args ...interface{})

func (*Logger) Notice

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

Notice logs a message using NOTICE as log level.

func (*Logger) Output

func (l *Logger) Output(calldepth int, s string) error

func (*Logger) Outputf

func (l *Logger) Outputf(adjdepth int, fmt string, args ...interface{})

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

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

Panicln is equivalent to l.Critical(fmt.Sprintln()) followed by a call to panic().

func (*Logger) Prefix

func (l *Logger) Prefix() string

func (*Logger) Print

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

func (*Logger) Printf

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

func (*Logger) Println

func (l *Logger) Println(v ...interface{})

func (*Logger) Re

func (l *Logger) Re(a Annotater) *Logger

Re returns a new logger that annotates log messages with the appropriate context (as defined by the Annotater)

func (*Logger) SetBackend

func (l *Logger) SetBackend(b LeveledBackend)

func (*Logger) SetFlags

func (l *Logger) SetFlags(flag int)

func (*Logger) SetPrefix

func (l *Logger) SetPrefix(p string)

func (*Logger) Warning

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

Warning 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
	Annotations []Annotation
	// 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

func (*Record) Message

func (r *Record) Message() string

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL