log0

README

log0

Simple logging for Go.

---

log0 is a simple logging adapter that simply provides clean and convenient methods for logging. It uses bufio.Writer as the output for the performance benefits of buffered writes as well as compatibility with any io.Writer.

The simplest way to use it is via Default(), which creates a Logger instance that uses os.Stdout as the output.

var log = log0.Default()

func main() {
    // calls Flush() on the bufio.Writer
    defer log.Close()
    log.Info("This message should print at the 'INFO' level.")
}

Here is an example of the default logging format:

Sat Jan 20 13:04:54 CET 2018 [INFO] - This should print. :: main.go:10 -> main.main
Sat Jan 20 13:04:54 CET 2018 [WARN] - Calling log from private function. :: main.go:16 -> main.privateFunc
Sat Jan 20 13:04:54 CET 2018 [ERROR] - Calling log from public function. :: main.go:20 -> main.PublicFunc

You can use any bufio.Writer and as such it can be a drop-in replacement for current solutions. This opens up the possibility to make use of features, like buffer limit, with no added cost.

Stack trace

The default logger created with Default() scans the stack trace for each individual log, to retrieve information about file name, line number and function name. This is a run-time operation, which is quite expensive, so it can be turned off via the ShowTrace boolean.

The trace is a runtime.Frame of the scope which called the logger method.

Formats

• default log format is constructed in the following manner:

<time(UNIXDate)> [<level>] - <message> :: <filename>:<line> -> <function>

• simple log format follows this pattern:

<time> [<level>] <function> - <message>

Levels

The methods will only actually write logs if the logging level is included in the Levels of the logger. The following levels are available:

• FINEST
• FINE
• DEBUG
• TRACE
• INFO
• WARNING
• ERROR
• FATAL
• OFF - this turns off all logging

There are 3 methods to set the logging level dynamically:

Level()

This method sets the logging level, which includes the level set and all levels above, e.g.: setting to DEBUG will include: DEBUG, TRACE, INFO, WARNING, ERROR and FATAL.

// comes with logging level of INFO
var log = log0.Default()

func main() {
    // Sets level to DEBUG
    log.Level(log0.DEBUG)
}

Include()

This method adds any number of log levels to the Levels of the logger, e.g.: adding DEBUG to the default list of INFO - FATAL.

var log = log0.Default()

func main() {
    log.Include(log0.DEBUG)
}

Exclude()

This method can be used to silence a specific level, by removing it from the Levels, e.g.: removing ERROR from the default list leaves: INFO, WARNING and FATAL.

var log = log0.Default()

func main() {
    log.Exclude(log0.ERROR)
}

Contributing

Bug reports and pull requests are welcome!

License

Copyright 2018 Daniel Emod Kovacs

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Overview

Package log0 is a simple, pluggable logging library.

A more detailed usage guide can be found at https://github.com/danielkov/log0.

Simple example:

var log = log0.Default()

func main() {
	defer log.Close()
	log.Info("This message will log at INFO level.")
}

Index

• Constants
• Variables
• func DefaultFormatter(l Log) string
• func SimpleFormatter(l Log) string
• type Formatter
• type Log
• type Logger
  • func Default() Logger
  • func New(w *bufio.Writer, l []level, t bool, f Formatter) Logger
  • func (l *Logger) Close() error
  • func (l *Logger) Debug(message string) error
  • func (l *Logger) Error(message string) error
  • func (l *Logger) Exclude(levels ...level)
  • func (l *Logger) Fatal(message string) error
  • func (l *Logger) Fine(message string) error
  • func (l *Logger) Finest(message string) error
  • func (l *Logger) Include(levels ...level)
  • func (l *Logger) Info(message string) error
  • func (l *Logger) Level(lv level)
  • func (l *Logger) Trace(message string) error
  • func (l *Logger) Warning(message string) error

Constants

const (
	FINEST level = iota
	FINE
	DEBUG
	TRACE
	INFO
	WARNING
	ERROR
	FATAL
	OFF
)

Pseudo-enum of all logging levels

Variables

var (
	DefaultLevels = []level{INFO, WARNING, ERROR, FATAL}
)

Logging levels to use by default

Functions

func DefaultFormatter

func DefaultFormatter(l Log) string

DefaultFormatter is a Formatter function that returns the log in the format:

<time(UNIXDate)> [<level>] - <message> :: <filename>:<line> -> <function>

func SimpleFormatter

func SimpleFormatter(l Log) string

SimpleFormatter is a Formatter function that returns the log in the format:

<time> [<level>] <function> - <message>

Types

type Formatter

type Formatter func(Log) string

Formatter is a function type that is used on the Logger to create a string representation of the Log object

type Log

type Log struct {
	Level   level
	Time    time.Time
	Message string
	Frame   runtime.Frame
}

Log is a struct that contains meta data about the log that is created by the methods on Logger. Not every Log will be written, only the ones that have a level, which is included in the Loggers levels.

type Logger

type Logger struct {
	Writer    *bufio.Writer
	Includes  []level
	ShowTrace bool
	Formatter Formatter
}

Logger is a struct that takes in a *bufio.Writer which it writes to with the corresponding logging methods

func Default

func Default() Logger

Default is a function that returns an instance of Logger with the default config: os.Stdout as output, INFO level, trace generation and DefaultFormatter

func New

func New(w *bufio.Writer, l []level, t bool, f Formatter) Logger

New is a function that returns an instance of Logger

func (*Logger) Close

func (l *Logger) Close() error

Close is a method that cleans up after the Logger is no longer needed. Calling Close() is important because it flushes the buffered writer

func (*Logger) Debug

func (l *Logger) Debug(message string) error

Debug is a logger method that logs the message with the Loggers formatting at DEBUG level

func (*Logger) Error

func (l *Logger) Error(message string) error

Error is a logger method that logs the message with the Loggers formatting at ERROR level

func (*Logger) Exclude

func (l *Logger) Exclude(levels ...level)

Exclude is a method that takes anu number of levels and removes them from the list of log levels to be displayed

func (*Logger) Fatal

func (l *Logger) Fatal(message string) error

Fatal is a logger method that logs the message with the Loggers formatting at FATAL level

func (*Logger) Fine

func (l *Logger) Fine(message string) error

Fine is a logger method that logs the message with the Loggers formatting at FINE level

func (*Logger) Finest

func (l *Logger) Finest(message string) error

Finest is a logger method that logs the message with the Loggers formatting at FNST level

func (*Logger) Include

func (l *Logger) Include(levels ...level)

Include is a method that takes any number of levels and adds them to the list of log levels to be displayed

func (*Logger) Info

func (l *Logger) Info(message string) error

Info is a logger method that logs the message with the Loggers formatting at INFO level

func (*Logger) Level

func (l *Logger) Level(lv level)

Level is a method that takes a single level, above which it will include all levels in the logs with the supplied level included

func (*Logger) Trace

func (l *Logger) Trace(message string) error

Trace is a logger method that logs the message with the Loggers formatting at TRACE level

func (*Logger) Warning

func (l *Logger) Warning(message string) error

Warning is a logger method that logs the message with the Loggers formatting at WARN level