Logging, distilled

Overview

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

Issues
Owner
Akshay Moghe
Akshay Moghe
Parse awesome-go README file and generate a new README file with repo info.

Awesome Go Extra All data are from awesome-go and GitHub API. Audio and Music Libraries for manipulating audio. Name Description Star Open Issues Crea

Wendell Sun 13 Jul 24, 2021
A pure Go contextual logging library with "batteries included"

Cue Overview Cue implements contextual logging with "batteries included". It has thorough test coverage and supports logging to stdout/stderr, file, s

Bob Ziuchkovski 26 Sep 16, 2019
Logging, distilled

What is distillog? distillog aims to offer a minimalistic logging interface that also supports log levels. It takes the stdlib API and only slightly e

Akshay Moghe 26 Jun 21, 2021
Logur is an opinionated collection of logging best practices

Logur is an opinionated collection of logging best practices. Table of Contents Preface Features Installation Usage FAQ Why not just X logger? Why not

Logur 129 Jul 16, 2021
Golang logging library

Golang logging library Package logging implements a logging infrastructure for Go. Its output format is customizable and supports different logging ba

Örjan Fors 1.7k Jul 17, 2021
Structured, pluggable logging for Go.

Logrus Logrus is a structured logger for Go (golang), completely API compatible with the standard library logger. Logrus is in maintenance-mode. We wi

Simon Eskildsen 18.3k Jul 24, 2021
Logrus is a structured, pluggable logging for Go.

Logrus is a structured logger for Go (golang), completely API compatible with the standard library logger.

Simon Eskildsen 274 May 25, 2021
A simple logging interface for Go

A more minimal logging API for Go Before you consider this package, please read this blog post by the inimitable Dave Cheney. I really appreciate what

null 430 Jul 23, 2021
Dead simple, super fast, zero allocation and modular logger for Golang

Onelog Onelog is a dead simple but very efficient JSON logger. It is one of the fastest JSON logger out there. Also, it is one of the logger with the

Francois Parquet 396 Jul 16, 2021
Structured Logging Made Easy

Structured Logging Made Easy Features Dependency Free Simple and Clean Interface Consistent Writer IOWriter, io.Writer wrapper FileWriter, rotating &

phuslu 386 Jul 22, 2021
A minimal and extensible structured logger

⚠️ PRE-RELEASE ⚠️ DO NOT IMPORT THIS MODULE YOUR PROJECT WILL BREAK package log package log provides a minimal interface for structured logging in ser

Go kit 54 Jul 21, 2021
Parametrized JSON logging library in Golang which lets you obfuscate sensitive data and marshal any kind of content.

Noodlog Summary Noodlog is a Golang JSON parametrized and highly configurable logging library. It allows you to: print go structs as JSON messages; pr

Gyoza Tech 23 Apr 28, 2021
Fully asynchronous, structured, pluggable logging for Go.

logr Logr is a fully asynchronous, contextual logger for Go. It is very much inspired by Logrus but addresses two issues: Logr is fully asynchronous,

Mattermost 10 Jun 16, 2021
Simple, customizable, leveled and efficient logging in Go

log Simple, customizable, leveled and efficient logging in Go Installation go get -u github.com/ermanimer/log Features log is a simple logging package

Erman İmer 22 Jul 13, 2021