logr

README

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 he has to say, and it largely aligns with my own experiences. Too many choices of levels means inconsistent logs.

This package offers a purely abstract interface, based on these ideas but with a few twists. Code can depend on just this interface and have the actual logging implementation be injected from callers. Ideally only main() knows what logging implementation is being used.

Differences from Dave's ideas

The main differences are:

1. Dave basically proposes doing away with the notion of a logging API in favor of fmt.Printf(). I disagree, especially when you consider things like output locations, timestamps, file and line decorations, and structured logging. I restrict the API to just 2 types of logs: info and error.

Info logs are things you want to tell the user which are not errors. Error logs are, well, errors. If your code receives an error from a subordinate function call and is logging that error and not returning it, use error logs.

1. Verbosity-levels on info logs. This gives developers a chance to indicate arbitrary grades of importance for info logs, without assigning names with semantic meaning such as "warning", "trace", and "debug". Superficially this may feel very similar, but the primary difference is the lack of semantics. Because verbosity is a numerical value, it's safe to assume that an app running with higher verbosity means more (and less important) logs will be generated.

This is a BETA grade API. I have implemented it for glog. Until there is a significant 2nd implementation, I don't really know how it will change.

Documentation

Overview

Package logr defines abstract interfaces for logging. Packages can depend on these interfaces and callers can implement logging in whatever way is appropriate.

This design derives from Dave Cheney's blog:

http://dave.cheney.net/2015/11/05/lets-talk-about-logging

This is a BETA grade API. Until there is a significant 2nd implementation, I don't really know how it will change.

Index

• type InfoLogger
• type Logger

Types

type InfoLogger

type InfoLogger interface {
	// Info logs a non-error message.  This is behaviorally akin to fmt.Print.
	Info(args ...interface{})

	// Infof logs a formatted non-error message.
	Infof(format string, args ...interface{})

	// Enabled test whether this InfoLogger is enabled.  For example,
	// commandline flags might be used to set the logging verbosity and disable
	// some info logs.
	Enabled() bool
}

InfoLogger represents the ability to log non-error messages.

type Logger

type Logger interface {
	// All Loggers implement InfoLogger.  Calling InfoLogger methods directly on
	// a Logger value is equivalent to calling them on a V(0) InfoLogger.  For
	// example, logger.Info() produces the same result as logger.V(0).Info.
	InfoLogger

	// Error logs a error message.  This is behaviorally akin to fmt.Print.
	Error(args ...interface{})

	// Errorf logs a formatted error message.
	Errorf(format string, args ...interface{})

	// V returns an InfoLogger value for a specific verbosity level.  A higher
	// verbosity level means a log message is less important.
	V(level int) InfoLogger

	// NewWithPrefix returns a Logger which prefixes all messages.
	NewWithPrefix(prefix string) Logger

	// WithField returns a logger with the given fields
	WithField(name string, value interface{}) Logger
}

Logger represents the ability to log messages, both errors and not.