logger

README

logger

A package that provides an adaptable logger implementation to be used by other re-usable modules that wish to emit logs using a logger supplied by the consuming project.

Such packages would provide a mechanism for "injecting" a logger exported by this package. Automatic log enrichment (from context) can also be established by those modules implementing an init() function to register an enrichment func.

How It Works

Despite the name, this logger package does not implement an actual logger, rather it provides a delegate that routes logging calls via an adapter to a logger configured by an application/service. A consuming project will configure whatever logger it wishes and then wrap that with an adapter so that it may be injected into any modules or packages that support logger.

Adapters are provided in this package for logrus and the standard log package.

A NulAdapter is also provided which produces no log output what-so-ever (logging to NUL).

---

How to Use Logger

In an Application or Service Project

IF NEEDED: Implement an Adapter (if one does not already exist for your preferred logger)

1. Configure your logger
2. Wrap your project logger in a Logger using the appropriate Adapter
3. Pass the Logger into any modules/packages that support shared logging
4. OPTIONAL: Register Enrichment functions provided by your project and any other modules (they do not need to be logging via a Logger in order to provide enrichment)
5. Enjoy your logs

In a Module/Package

1. Provide a means for a Logger to be configured for use by your module/package
   • EITHER: import this module and use the Logger type directly
   • OR: employ an interface type (declared in your module/package) that is compatible with those methods of Logger that your code uses
2. OPTIONAL: Export an Enrichment function
3. OPTIONAL: Add log enrichment data to context where appropriate and use errorcontext to return errors with context for enriched logging
4. Write logs from your code using the configured Logger
   • Ensure that logs are not written if no Logger is configured (provide a no-op implementation of your defined interface or initialise a default Logger with a NulAdapter if you don't mind taking a dependency on this logger module)

Documentation

Index

• Variables
• func WithEnrichment(d EnrichmentFunc)
• type Adapter
• type EnrichmentFunc
• type Level
• type LogEntry
• type Logger
  • func Nul() Logger
  • func UsingLogrus(ctx context.Context, log *logrus.Logger) Logger
  • func UsingStdLog() Logger
• type LogrusAdapter
  • func (log *LogrusAdapter) Emit(level Level, s string)
  • func (log *LogrusAdapter) NewEntry() Adapter
  • func (log *LogrusAdapter) WithField(name string, value any) Adapter
• type NulAdapter
  • func (*NulAdapter) Emit(Level, string)
  • func (nul *NulAdapter) NewEntry() Adapter
  • func (nul *NulAdapter) WithField(string, any) Adapter
• type StdLogAdapter
  • func (a *StdLogAdapter) Emit(level Level, s string)
  • func (log *StdLogAdapter) NewEntry() Adapter
  • func (log *StdLogAdapter) WithField(name string, value any) Adapter

Variables

var ExitFn func(int) = os.Exit

Functions

func WithEnrichment

func WithEnrichment(d EnrichmentFunc)

Types

type Adapter

type Adapter interface {
	Emit(Level, string)
	NewEntry() Adapter
	WithField(string, any) Adapter
}

type EnrichmentFunc

type EnrichmentFunc func(context.Context, LogEntry) LogEntry

type Level

type Level int

const (
	Fatal Level = iota
	Error
	Warn
	Info
	Debug
	Trace
)

NOTE: though levels are modelled on logrus, Panic is not supported

type LogEntry

type LogEntry interface {
	Debug(s string)
	Debugf(format string, args ...any)
	Error(err error)
	Errorf(format string, args ...any)
	Fatal(s string)
	Fatalf(format string, args ...any)
	FatalError(err error)
	Info(s string)
	Infof(format string, args ...any)
	Trace(s string)
	Tracef(format string, args ...any)
	Warn(s string)
	Warnf(format string, args ...any)
	WithContext(context.Context) LogEntry
	WithField(name string, value any) LogEntry
}

type Logger

type Logger interface {
	FromContext(context.Context) LogEntry
	NewEntry() LogEntry
}

func Nul

func Nul() Logger

func UsingLogrus

func UsingLogrus(ctx context.Context, log *logrus.Logger) Logger

func UsingStdLog

func UsingStdLog() Logger

type LogrusAdapter

type LogrusAdapter struct {
	*logrus.Logger
}

func (*LogrusAdapter) Emit

func (log *LogrusAdapter) Emit(level Level, s string)

func (*LogrusAdapter) NewEntry

func (log *LogrusAdapter) NewEntry() Adapter

func (*LogrusAdapter) WithField

func (log *LogrusAdapter) WithField(name string, value any) Adapter

type NulAdapter

type NulAdapter struct{}

func (*NulAdapter) Emit

func (*NulAdapter) Emit(Level, string)

func (*NulAdapter) NewEntry

func (nul *NulAdapter) NewEntry() Adapter

func (*NulAdapter) WithField

func (nul *NulAdapter) WithField(string, any) Adapter

type StdLogAdapter

type StdLogAdapter struct {
	// contains filtered or unexported fields
}

func (*StdLogAdapter) Emit

func (a *StdLogAdapter) Emit(level Level, s string)

func (*StdLogAdapter) NewEntry

func (log *StdLogAdapter) NewEntry() Adapter

func (*StdLogAdapter) WithField

func (log *StdLogAdapter) WithField(name string, value any) Adapter