README
¶
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(vialumberjack) - 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
- Create an issue, describe the bugfix/feature you wish to implement.
- Fork the repository
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - 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 ¶
- func Close()
- func Debugf(format string, v ...interface{})
- func Debugln(v ...interface{})
- func Errorf(format string, v ...interface{})
- func Errorln(v ...interface{})
- func Infof(format string, v ...interface{})
- func Infoln(v ...interface{})
- func SetOutput(out io.WriteCloser)
- func Warningf(format string, v ...interface{})
- func Warningln(v ...interface{})
- type Logger
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Debugf ¶
func Debugf(format string, v ...interface{})
Debugf 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 Infof ¶
func Infof(format string, v ...interface{})
Infof 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.
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 ¶
NewNullLogger returns a logger that drops messages (outputs to /dev/null).
func NewStderrLogger ¶
NewStderrLogger returns a Logger that outputs messages to Stderr.
func NewStdoutLogger ¶
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 ¶
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.
Source Files