log

README

Log

Log is a logging interface for Go. That's it. Pass around the interface.

Rationale

Users want to standardise logging. Sometimes libraries log. We leave the underlying logging implementation to the user while allowing libraries to log by simply expecting something that satisfies the Logger interface. This leaves the user free to pre-configure structure, output, etc.

Interface

The interface is minimalistic on purpose:

type Logger interface {
    Log(v ...interface{})
    Logf(format string, v ...interface{})
}

For more motivation for this minimal interface, see Dave Cheney's blog post.

Implementations

Libraries will only need the Logger interface, although they may choose to use the nest package to create subloggers with additional context.

Calling code will need to create a Logger interface, and there are a number of implementations and wrappers available to make that easy:

• capture is an implementation that saves logged lines in memory. It is especially useful for unit tests that want to check for logged messages.
• fmt is an implementation wrapping an io.Writer like os.Stdout. It uses fmt.Sprint and Sprintf to generate the logged lines.
• info is an implementation wrapping Info and Infof calls. It can be used to wrap implementations like glog.Verbose and logrus.Entry.
• print is an implementation wrapping Print and Printf calls. It can be used to wrap implementations like glog.Verbose.
• log is an implementation wrapping log.Print and log.Printf.

Outside of this repository, there are additional wrappers for:

• appengine/log, here.
• logrus, here. Although as mentioned above, you can also use the info and print wrappers for logrus.

The Logger interface is also simple enough to make writing your own implementation or wrapper very straightforward.

Example

Pre-configure a logger using WithFields and pass it as an option to a library:

import (
	"github.com/go-log/log/print"
	"github.com/lib/foo"
	"github.com/sirupsen/logrus"
)

logger := print.New(logrus.WithFields(logrus.Fields{
	"library": "github.com/lib/foo",
}))

f := foo.New(logger)

Related projects

github.com/go-logr/logr is a similar interface approach to logging, although the logr.Logger interface is more elaborate.

Documentation

Overview

Package log provides a log interface

Index

• func Log(v ...interface{})
• func Logf(format string, v ...interface{})
• type Logger

Functions

func Log

func Log(v ...interface{})

Log logs using the default logger

func Logf

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

Logf logs formatted using the default logger

Types

type Logger

type Logger interface {
	// Log inserts a log entry.  Arguments may be handled in the manner
	// of fmt.Print, but the underlying logger may also decide to handle
	// them differently.
	Log(v ...interface{})
	// Logf insets a log entry.  Arguments are handled in the manner of
	// fmt.Printf.
	Logf(format string, v ...interface{})
}

Logger is a generic logging interface

var (
	// The global default logger
	DefaultLogger Logger = &noOpLogger{}
)