logging.go

package logging

import (
	"context"
	"sync"
)

var (
	mu           sync.Mutex // protects usingBackend and useConfig
	usingBackend *Backend   // active backend, nil until the first Init or logger request
	useConfig    = NewConfig()
)

// Init do logging subsystem initialization. Returns error if init failed.
// It makes a new backend using default configuration modified with options.
// The previous backend stays active if Init fails. Loggers made before Init keep using the previous backend.
// Call Init once at the start of the program, before creating loggers.
func Init(opts ...Option) error {
	config := NewConfig()
	config.Apply(opts...)

	if err := config.Validate(); err != nil {
		return err
	}

	backend := new(Backend)
	if err := backend.Init(*config); err != nil {
		return wrapErr(err, "backend")
	}

	mu.Lock()
	usingBackend = backend
	useConfig = config
	mu.Unlock()

	return nil
}

// MustInit do logging subsystem initialisation. Panics if init failed.
// Simply wraps Init doing panic on error.
// Takes configuration Option's to overwrite defaults.
func MustInit(opts ...Option) {
	if err := Init(opts...); err != nil {
		panic(err)
	}
}

// activeBackend returns the backend in use. Initialises it using current configuration if Init was not called yet,
// so package level loggers are usable before Init. Such loggers do not follow later Init, use Default for that.
func activeBackend() *Backend {
	mu.Lock()
	defer mu.Unlock()

	if usingBackend == nil {
		backend := new(Backend)
		backend.MustInit(*useConfig)
		usingBackend = backend
	}

	return usingBackend
}

// Sync flushes any buffered log entries of the active backend.
func Sync() error {
	return activeBackend().Sync()
}

// NewLogger initializes a new logger instance.
// Optionally takes level to set. If no logging level specified the configured Level is used.
// Uses default configuration if Init is not called before.
// NOTE: this logger requires Sync() called manually to write any buffered log entry before exit.
// To have automatically synced logger use NewLoggerCtx instead.
func NewLogger(levels ...Level) Logger {
	return activeBackend().NewLogger(levels...)
}

// NewLoggerCtx initializes a new logger instance doing flushing any buffered log entries on context done.
// Takes logger context and optional logger level to set.
// If no logging level specified the configured Level is used.
// Automatically adds logging keys from context using any installed with WithContextExtractors.
func NewLoggerCtx(ctx context.Context, levels ...Level) Logger {
	return activeBackend().NewLoggerCtx(ctx, levels...)
}

// NewNamedLogger initializes a new named logger.
// Takes logger name to initialize and optional logging level to set.
// The level specified with argument wins, then the level configured for the name in Config.CustomLevels,
// then the configured global Level.
// NOTE: this logger requires Sync() called manually to write any buffered log entry before exit.
// To have automatically synced logger use NewNamedLoggerCtx instead.
func NewNamedLogger(name string, levels ...Level) Logger {
	return activeBackend().NewNamedLogger(name, levels...)
}

// NewNamedLoggerCtx initializes a new named logger providing flushing buffered log entries on context done.
// Takes logger context, logger name and optional logging level to set, see NewNamedLogger for the level choice.
// Automatically adds logging keys from context using any installed with WithContextExtractors.
func NewNamedLoggerCtx(ctx context.Context, name string, levels ...Level) Logger {
	return activeBackend().NewNamedLoggerCtx(ctx, name, levels...)
}