distillog

package module
Version: v0.0.0-...-ae382b3 Latest Latest
Warning

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

Go to latest
Published: Jul 26, 2018 License: MIT Imports: 8 Imported by: 22

README

Build Status Documentation Go Report Card

What is distillog?

distillog aims to offer a minimalistic logging interface that also supports log levels. It takes the stdlib API and only slightly enhances it. Hence, you could think of it as levelled logging, distilled.

Yet another logging library for go(lang)?

Logging libraries are like opinions, everyone seems to have one -- Anon(?)

Most other logging libraries do either too little (stdlib) or too much (glog).

As with most other libraries, this one is opinionated. In terms of functionality it exposes, it attempts to sit somewhere between the stdlib and the majority of other logging libraries available (but leans mostly towards the spartan side of stdlib).

The stdlib does too little, you say?

Just a smidge.

Presenting varying levels of verbosity (or severity) are an important part of what makes a program more usable or debuggable. For example, debug or info level messages may be useful to the developers during the development cycle. These messages may be dropped or suppressed in production since they are not useful to everyone. Similarly warning messages may be emitted when a error has been gracefully handled but the program would like to notify its human overlords of some impending doom.

In most cases, some downstream entity "knows" how to filter the messages and keep those that are relevant to the environment. As evidence of this, most other languages have log libraries that support levels. Similarly some programs offer varying verbosity levels (e.g. -v, -vv etc). The golang stdlib takes a much more spartan approach (exposing only Println and friends) so using it in programs to emit messages of varying interest/levels can get tedious (manual prefixes, anyone?). This is where distillog steps in. It aims to slightly improve on this minimalstic logging interface. Slightly.

Other libraries do too much, you say?

Ever used log.Panicf or log.Fatalf? Exiting your program is not something your log library should be doing! Similarly, other libraries offer options for maintaining old log files and rotating them. Your logging library shouldn't need to care about this. Whatever facility (other libraries call this a "backend") messages are sent to should determine how old messages are handled. distillog prefers that you use lumberjack (or an equivalent WriteCloser) depending on where you choose to persist the messages.

But log file rotation is absolutely necessary!

Agreed, and someone's gotta do it, but it need not be your logging library!

You can use distillog along with a lumberjack "backend". It provides an io.WriteCloser which performs all the magic you need. Initialize a logger using distillog.NewStream, pass it an instance of the io.WriteCloser that lumberjack returns, et voila, you have a logger that does what you need.

And how is distillog different?

distillog aims to offer a only slightly richer interface than the stdlib.

To this end, it restricts itself to:

  • presenting a minimal interface so that you can emit levelled log messages
  • providing logger implementations for logging to the most common backends
    • streams - e.g. stderr/stdout
    • files - anything via io.WriteCloser (via lumberjack)
    • syslog
  • avoid taking on any non-essential responsibilities (colors, ahem)
  • expose a logger interface, instead of an implementation

Expose an interface? Why?

By exposing an interface you can write programs that use levelled log messages, but switch between logging to various facilities by simply instantiating the appropriate logger as determined by the caller (Your program can offer a command-line switch like so - --log-to=[syslog,stderr,<file>] and the simply instantiate the appropriate logger).

Usage/examples:

As seen in the godoc, the interface is limited to:

type Logger interface {
	Debugf(format string, v ...interface{})
	Debugln(v ...interface{})

	Infof(format string, v ...interface{})
	Infoln(v ...interface{})

	Warningf(format string, v ...interface{})
	Warningln(v ...interface{})

	Errorf(format string, v ...interface{})
	Errorln(v ...interface{})

	Close() error
}

Log to stdout, or stderr using a logger instantiated like so:

outLogger := distillog.NewStdoutLogger("test")

errLogger := distillog.NewStderrLogger("test")

sysLogger := distillog.NewSyslogLogger("test")

Alternatively, you can use the package for your logging needs:

import log "github.com/amoghe/distillog"

// ... later ...

log.Infoln("Starting program")
log.Debugln("initializing the frobnicator")
log.Warningln("frobnicator failure detected, proceeding anyways...")
log.Infoln("Exiting")

If you have a file you wish to log to, you should open the file and instantiate a logger using the file handle, like so:

if fileHandle, err := ioutil.Tempfile("/tmp", "distillog-test"); err == nil {
        fileLogger := distillog.NewStreamLogger("test", fileHandle)
}

If you need a logger that manages the rotation of its files, use lumberjack, like so:

lumberjackHandle := &lumberjack.Logger{
        Filename:   "/var/log/myapp/foo.log",
        MaxSize:    500,                       // megabytes
        MaxBackups: 3,
        MaxAge:     28,                        // days
}

logger := distillog.NewStreamLogger("tag", lumberjackHandle)

// Alternatively, configure the pkg level logger to emit here

distillog.SetOutput(lumberjackHandle)

Once instantiated, you can log messages, like so:

var := "World!"
myLogger.Infof("Hello, %s", var)
myLogger.Warningln("Goodbye, cruel world!")

Contributing

  1. Create an issue, describe the bugfix/feature you wish to implement.
  2. Fork the repository
  3. Create your feature branch (git checkout -b my-new-feature)
  4. Commit your changes (git commit -am 'Add some feature')
  5. Push to the branch (git push origin my-new-feature)
  6. Create a new Pull Request

License

See LICENSE.txt

Documentation

Overview

Package distillog provides a minimalistic logging interface (inspired by the stdlib) that also supports levelled logging.

You can instantiate a logger (that adheres to the Logger interface) or use the pkg level log functions (like the stdlib).

You can set where the log messages are sent to by either either instantiating your own logger using the appropriate constructor function, or by using SetOutput to configure the pkg level logger.

You may also use `lumberjack` or a similar library in conjunction with this one to manage (rotate) your log files.

Visit the README at https://github.com/amoghe/distillog

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Close

func Close()

Close closes the stream to which the default logger logs to

func Debugf

func Debugf(format string, v ...interface{})

Debugf logs a message to stderr at 'debug' level

func Debugln

func Debugln(v ...interface{})

Debugln logs a message to stderr at 'debug' level

func Errorf

func Errorf(format string, v ...interface{})

Errorf logs a message to stderr at 'error' level

func Errorln

func Errorln(v ...interface{})

Errorln logs a message to stderr at 'error' level

func Infof

func Infof(format string, v ...interface{})

Infof logs a message to stderr at 'info' level

func Infoln

func Infoln(v ...interface{})

Infoln logs a message to stderr at 'info' level

func SetOutput

func SetOutput(out io.WriteCloser)

SetOutput allows you to configure the package level logger to emit to the specified output stream. NOTE: this is not safe when called concurrently from multiple goroutines. This should typically be called once during program initialization before spawning goroutines that may use the log.

func Warningf

func Warningf(format string, v ...interface{})

Warningf logs a message to stderr at 'warn' level

func Warningln

func Warningln(v ...interface{})

Warningln logs a message to stderr at 'warn' level

Types

type Logger

type Logger interface {
	Debugf(format string, v ...interface{})
	Debugln(v ...interface{})

	Infof(format string, v ...interface{})
	Infoln(v ...interface{})

	Warningf(format string, v ...interface{})
	Warningln(v ...interface{})

	Errorf(format string, v ...interface{})
	Errorln(v ...interface{})

	Close() error
}

Logger defines a distilled interface for logging messages from your program. Note: All functions append a trailing newline if one doesn't exist.

func NewNullLogger

func NewNullLogger(tag string) Logger

NewNullLogger returns a logger that drops messages (outputs to /dev/null).

func NewStderrLogger

func NewStderrLogger(tag string) Logger

NewStderrLogger returns a Logger that outputs messages to Stderr.

func NewStdoutLogger

func NewStdoutLogger(tag string) Logger

NewStdoutLogger returns a Logger that outputs messages to Stdout.

func NewStreamLogger

func NewStreamLogger(tag string, stream io.WriteCloser) Logger

NewStreamLogger returns a Logger that outputs messages to the specified stream.

func NewSyslogLogger

func NewSyslogLogger(tag string) Logger

NewSyslogLogger returns a Logger that sends messages to the Syslog daemon. This will panic if it is unable to connect to the local syslog daemon.

Jump to

Keyboard shortcuts

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