dlog

Documentation

Overview

Package dlog implements a generic logger facade.

There are two first-class things of value in this package:

First: The Logger interface. This is a simple structured logging interface that is mostly trivial to implement on top of most logging backends, and allows library code to not need to care about what specific logging system the calling program uses.

Second: The WithLogger, GetLogger, and WithLoggerField functions for tracking logger context. These allow you to painlessly associate a logger with a context.

If you are writing library code and want a logger, then you should take a context.Context as an argument, and then call GetLogger on that Context argument.

Index

• func WithLogger(ctx context.Context, logger Logger) context.Context
• func WithLoggerField(ctx context.Context, key string, value interface{}) context.Context
• type LogLevel
• type Logger
  • func GetLogger(ctx context.Context) Logger
  • func WrapLogrus(in logrusLogger) Logger
  • func WrapTB(in testing.TB, failOnError bool) Logger

Functions

func WithLogger

func WithLogger(ctx context.Context, logger Logger) context.Context

WithLogger returns a copy of ctx with logger associated with it, for future calls to GetLogger.

You should only really ever call WithLogger from the initial process set up (i.e. directly inside your 'main()' function).

func WithLoggerField

func WithLoggerField(ctx context.Context, key string, value interface{}) context.Context

WithLoggerField is a convenience wrapper for

WithLogger(ctx, GetLogger(ctx).WithField(key, value))

Types

type LogLevel

type LogLevel uint32

LogLevel is an abstracted common log-level type for for Logger.StdLogger().

const (
	// LogLevelError is for errors that should definitely be noted.
	LogLevelError LogLevel = iota
	// LogLevelWarn is for non-critical entries that deserve eyes.
	LogLevelWarn
	// LogLevelInfo is for general operational entries about what's
	// going on inside the application.
	LogLevelInfo
	// LogLevelDebug is for debugging.  Very verbose logging.
	LogLevelDebug
	// LogLevelTrace is for extreme debugging.  Even finer-grained
	// informational events than the Debug.
	LogLevelTrace
)

type Logger

type Logger interface {
	WithField(key string, value interface{}) Logger
	StdLogger(LogLevel) *log.Logger

	Tracef(format string, args ...interface{})
	Debugf(format string, args ...interface{})
	Infof(format string, args ...interface{})
	Printf(format string, args ...interface{})
	Warnf(format string, args ...interface{})
	Warningf(format string, args ...interface{})
	Errorf(format string, args ...interface{})

	Trace(args ...interface{})
	Debug(args ...interface{})
	Info(args ...interface{})
	Print(args ...interface{})
	Warn(args ...interface{})
	Warning(args ...interface{})
	Error(args ...interface{})

	Traceln(args ...interface{})
	Debugln(args ...interface{})
	Infoln(args ...interface{})
	Println(args ...interface{})
	Warnln(args ...interface{})
	Warningln(args ...interface{})
	Errorln(args ...interface{})
}

Logger is a generic logging interface that most loggers implement, so that consumers don't need to care about the actual log implementation.

Note that unlike logrus.FieldLogger, it does not include Fatal or Panic logging options. Do proper error handling! Return those errors!

func GetLogger

func GetLogger(ctx context.Context) Logger

GetLogger returns the Logger associated with ctx. If ctx has no Logger associated with it, a "default" logger is returned. This function always returns a usable logger.

func WrapLogrus

func WrapLogrus(in logrusLogger) Logger

WrapLogrus converts a logrus *Logger (or *Entry) into a generic Logger.

You should only really ever call WrapLogrus from the initial process set up (i.e. directly inside your 'main()' function), and you should pass the result directly to WithLogger.

func WrapTB

func WrapTB(in testing.TB, failOnError bool) Logger

WrapTB converts a testing.TB (that is: either a *testing.T or a *testing.B) into a generic Logger.

Naturally, you should only use this from inside of your *_test.go files.