logging

README

logging

Simple logging package in Go.

Install

$ go get github.com/koding/logging

Features

• Log levels (DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL)
• Different colored output for different levels (can be disabled)
• No global state in package
• Customizable logging handlers
• Customizable formatters
• Log to multiple backends concurrently
• Context based (inherited) loggers

Example Usage

See https://github.com/koding/logging/blob/master/example/example.go

Documentation

Overview

Package logging is an alternative to log package in standard library.

Index

• Variables
• func Critical(format string, args ...interface{})
• func Debug(format string, args ...interface{})
• func Error(format string, args ...interface{})
• func Fatal(format string, args ...interface{})
• func Info(format string, args ...interface{})
• func Notice(format string, args ...interface{})
• func Panic(format string, args ...interface{})
• func Warning(format string, args ...interface{})
• type BaseHandler
  • func NewBaseHandler() *BaseHandler
  • func (h *BaseHandler) FilterAndFormat(rec *Record) string
  • func (h *BaseHandler) SetFormatter(f Formatter)
  • func (h *BaseHandler) SetLevel(l Level)
• type Color
• type CustomFormatter
  • func (f *CustomFormatter) Format(rec *Record) string
• type Formatter
• type Handler
• type Level
• type Logger
  • func NewCustom(name string, debug bool) Logger
  • func NewLogger(name string) Logger
• type MultiHandler
  • func NewMultiHandler(handlers ...Handler) *MultiHandler
  • func (b *MultiHandler) Close()
  • func (b *MultiHandler) Handle(rec *Record)
  • func (b *MultiHandler) SetFormatter(f Formatter)
  • func (b *MultiHandler) SetLevel(l Level)
• type Record
• type SinkHandler
  • func NewSinkHandler(inner Handler, bufSize int) *SinkHandler
  • func (b *SinkHandler) Close()
  • func (b *SinkHandler) Handle(rec *Record)
  • func (b *SinkHandler) SetFormatter(f Formatter)
  • func (b *SinkHandler) SetLevel(l Level)
  • func (b *SinkHandler) Status() (int, int)
• type SyslogHandler
  • func NewSyslogHandler(tag string) (*SyslogHandler, error)
  • func (b *SyslogHandler) Close()
  • func (b *SyslogHandler) Handle(rec *Record)
• type WriterHandler
  • func NewWriterHandler(w io.Writer) *WriterHandler
  • func (b *WriterHandler) Close()
  • func (b *WriterHandler) Handle(rec *Record)

Variables

var (
	// DefaultLogger holds default logger
	DefaultLogger Logger = NewLogger(procName())

	// DefaultLevel holds default value for loggers
	DefaultLevel Level = INFO

	// DefaultHandler holds default handler for loggers
	DefaultHandler Handler = StderrHandler

	// DefaultFormatter holds default formatter for loggers
	DefaultFormatter Formatter = &defaultFormatter{}

	// StdoutHandler holds a handler with outputting to stdout
	StdoutHandler = NewWriterHandler(os.Stdout)

	// StderrHandler holds a handler with outputting to stderr
	StderrHandler = NewWriterHandler(os.Stderr)
)

var LevelColors = map[Level]Color{
	CRITICAL: MAGENTA,
	ERROR:    RED,
	WARNING:  YELLOW,
	NOTICE:   GREEN,
	INFO:     WHITE,
	DEBUG:    CYAN,
}

LevelColors provides mapping for log colors

var LevelNames = map[Level]string{
	CRITICAL: "CRITICAL",
	ERROR:    "ERROR",
	WARNING:  "WARNING",
	NOTICE:   "NOTICE",
	INFO:     "INFO",
	DEBUG:    "DEBUG",
}

LevelNames provides mapping for log levels

Functions

func Critical

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

Critical prints a critical level log message to the stderr. Arguments are handled in the manner of fmt.Printf.

func Debug

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

Debug prints a debug level log message to the stderr. Arguments are handled in the manner of fmt.Printf.

func Error

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

Error prints a error level log message to the stderr. Arguments are handled in the manner of fmt.Printf.

func Fatal

func Fatal(format string, args ...interface{})

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

func Info

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

Info prints a info level log message to the stderr. Arguments are handled in the manner of fmt.Printf.

func Notice

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

Notice prints a notice level log message to the stderr. Arguments are handled in the manner of fmt.Printf.

func Panic

func Panic(format string, args ...interface{})

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

func Warning

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

Warning prints a warning level log message to the stderr. Arguments are handled in the manner of fmt.Printf.

Types

type BaseHandler

type BaseHandler struct {
	Level     Level
	Formatter Formatter
}

BaseHandler provides basic functionality for handler

func NewBaseHandler

func NewBaseHandler() *BaseHandler

NewBaseHandler creates a newBaseHandler with default values

func (*BaseHandler) FilterAndFormat

func (h *BaseHandler) FilterAndFormat(rec *Record) string

FilterAndFormat filters any record according to loggging level

func (*BaseHandler) SetFormatter

func (h *BaseHandler) SetFormatter(f Formatter)

SetFormatter sets logging formatter for handler

func (*BaseHandler) SetLevel

func (h *BaseHandler) SetLevel(l Level)

SetLevel sets logging level for handler

type Color

type Color int

Color represents log level colors

const (
	BLACK Color = (iota + 30)
	RED
	GREEN
	YELLOW
	BLUE
	MAGENTA
	CYAN
	WHITE
)

Colors for different log levels.

type CustomFormatter

type CustomFormatter struct{}

func (*CustomFormatter) Format

func (f *CustomFormatter) Format(rec *Record) string

type Formatter

type Formatter interface {
	// Format the record and return a message.
	Format(*Record) (message string)
}

Formatter formats a record.

type Handler

type Handler interface {
	SetFormatter(Formatter)
	SetLevel(Level)

	// Handle single log record.
	Handle(*Record)

	// Close the handler.
	Close()
}

Handler handles the output.

type Level

type Level int

Level represent severity of logs

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

Logging levels.

type Logger

type Logger interface {
	// SetLevel changes the level of the logger. Default is logging.Info.
	SetLevel(Level)

	// SetHandler replaces the current handler for output. Default is logging.StderrHandler.
	SetHandler(Handler)

	// SetCallDepth sets the parameter passed to runtime.Caller().
	// It is used to get the file name from call stack.
	// For example you need to set it to 1 if you are using a wrapper around
	// the Logger. Default value is zero.
	SetCallDepth(int)

	// New creates a new inerhited context logger with given prefixes.
	New(prefixes ...interface{}) Logger

	// Fatal is equivalent to l.Critical followed by a call to os.Exit(1).
	Fatal(format string, args ...interface{})

	// Panic is equivalent to l.Critical followed by a call to panic().
	Panic(format string, args ...interface{})

	// Critical logs a message using CRITICAL as log level.
	Critical(format string, args ...interface{})

	// Error logs a message using ERROR as log level.
	Error(format string, args ...interface{})

	// Warning logs a message using WARNING as log level.
	Warning(format string, args ...interface{})

	// Notice logs a message using NOTICE as log level.
	Notice(format string, args ...interface{})

	// Info logs a message using INFO as log level.
	Info(format string, args ...interface{})

	// Debug logs a message using DEBUG as log level.
	Debug(format string, args ...interface{})
}

Logger is the interface for outputing log messages in different levels. A new Logger can be created with NewLogger() function. You can changed the output handler with SetHandler() function.

func NewCustom

func NewCustom(name string, debug bool) Logger

func NewLogger

func NewLogger(name string) Logger

NewLogger returns a new Logger implementation. Do not forget to close it at exit.

type MultiHandler

type MultiHandler struct {
	// contains filtered or unexported fields
}

MultiHandler sends the log output to multiple handlers concurrently.

func NewMultiHandler

func NewMultiHandler(handlers ...Handler) *MultiHandler

NewMultiHandler creates a new handler with given handlers

func (*MultiHandler) Close

func (b *MultiHandler) Close()

Close closes all handlers concurrently

func (*MultiHandler) Handle

func (b *MultiHandler) Handle(rec *Record)

Handle handles given record with all handlers concurrently

func (*MultiHandler) SetFormatter

func (b *MultiHandler) SetFormatter(f Formatter)

SetFormatter sets formatter for all handlers

func (*MultiHandler) SetLevel

func (b *MultiHandler) SetLevel(l Level)

SetLevel sets level for all handlers

type Record

type Record struct {
	Format      string        // Format string
	Args        []interface{} // Arguments to format string
	LoggerName  string        // Name of the logger module
	Level       Level         // Level of the record
	Time        time.Time     // Time of the record (local time)
	Filename    string        // File name of the log call (absolute path)
	Line        int           // Line number in file
	ProcessID   int           // PID
	ProcessName string        // Name of the process
}

Record contains all of the information about a single log message.

type SinkHandler

type SinkHandler struct {
	// contains filtered or unexported fields
}

SinkHandler sends log records to buffered channel, the logs are written in a dedicated routine consuming the channel.

func NewSinkHandler

func NewSinkHandler(inner Handler, bufSize int) *SinkHandler

NewSinkHandler creates SinkHandler with sink channel buffer size bufSize that wraps inner handler for writing logs. When SinkHandler is created a go routine is started. When not used always call Close to terminate go routine.

func (*SinkHandler) Close

func (b *SinkHandler) Close()

Close closes the sink channel, inner handler will be closed when all pending logs are processed. Close blocks until all the logs are processed.

func (*SinkHandler) Handle

func (b *SinkHandler) Handle(rec *Record)

Handle puts rec to the sink.

func (*SinkHandler) SetFormatter

func (b *SinkHandler) SetFormatter(f Formatter)

SetFormatter sets logging formatter for handler

func (*SinkHandler) SetLevel

func (b *SinkHandler) SetLevel(l Level)

SetLevel sets logging level for handler

func (*SinkHandler) Status

func (b *SinkHandler) Status() (int, int)

Status reports sink capacity and length.

type SyslogHandler

type SyslogHandler struct {
	*BaseHandler
	// contains filtered or unexported fields
}

SyslogHandler sends the logging output to syslog.

func NewSyslogHandler

func NewSyslogHandler(tag string) (*SyslogHandler, error)

func (*SyslogHandler) Close

func (b *SyslogHandler) Close()

func (*SyslogHandler) Handle

func (b *SyslogHandler) Handle(rec *Record)

type WriterHandler

type WriterHandler struct {
	*BaseHandler

	Colorize bool
	// contains filtered or unexported fields
}

WriterHandler is a handler implementation that writes the logging output to a io.Writer.

func NewWriterHandler

func NewWriterHandler(w io.Writer) *WriterHandler

NewWriterHandler creates a new writer handler with given io.Writer

func (*WriterHandler) Close

func (b *WriterHandler) Close()

Close closes WriterHandler

func (*WriterHandler) Handle

func (b *WriterHandler) Handle(rec *Record)

Handle writes any given Record to the Writer.