Documentation
¶
Overview ¶
Package logging provides a structured, leveled, file-only logger for wherehouse.
The package exposes a package-level singleton logger backed by log/slog with a text handler. Log rotation is optionally handled by lumberjack when MaxSizeMB is non-zero. The filesystem is abstracted via afero.Fs so tests can use an in-memory filesystem without touching disk.
Typical usage:
// In main or cmd/root.go:
if err := logging.Init(afero.NewOsFs(), logPath, "warn", 0, 0); err != nil {
fmt.Fprintf(os.Stderr, "warning: logging init failed: %v\n", err)
}
defer logging.Close()
// Anywhere in the application:
logging.Info("item moved", "item_id", id, "to", location)
// Component-scoped logger:
dbLog := logging.With("component", "database")
dbLog.Debug("query executed", "sql", query)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Close ¶
func Close() error
Close flushes and closes the underlying log file or lumberjack logger. Safe to call multiple times; subsequent calls are no-ops. Should be deferred immediately after a successful Init().
func Debug ¶
Debug logs a message at DEBUG level. No-op (discarded) if Init() has not been called or failed.
func Init ¶
Init initializes the package-level logger using the provided parameters.
fs is used for directory creation and (when maxSizeMB == 0) file opening. Lumberjack always uses the real OS for rotation because it owns the file handle.
Only the first call takes effect (sync.Once semantics). If the first call fails, subsequent calls return the same error without retrying.
logPath must be the resolved absolute path. level is a string level name (ParseLevel converts it). maxSizeMB == 0 disables rotation; > 0 enables lumberjack. maxBackups is coerced to 3 if maxSizeMB > 0 and maxBackups == 0.
func ParseLevel ¶
ParseLevel converts a string level name to slog.Level. Accepts "debug", "info", "warn", "warning", "error" (case-insensitive). Returns slog.LevelWarn for any unrecognized or empty value.
Types ¶
type Logger ¶
type Logger interface {
// Debug logs a message at DEBUG level.
Debug(msg string, args ...any)
// Info logs a message at INFO level.
Info(msg string, args ...any)
// Warn logs a message at WARN level.
Warn(msg string, args ...any)
// Error logs a message at ERROR level.
Error(msg string, args ...any)
// With returns a new Logger with the given key-value attributes
// pre-attached to every subsequent log record.
With(args ...any) Logger
}
Logger is the interface for structured, leveled logging. All methods match the slog.Logger method signatures to allow drop-in substitution. With returns a Logger (not slog.Logger) to keep the interface self-contained and mockable.
func GetLogger ¶
func GetLogger() Logger
GetLogger returns the package-level Logger. Returns a no-op Logger (io.Discard) if Init() has not been called. Prefer the package-level functions for ordinary use; use GetLogger() when you need to pass a Logger to another component.
func With ¶
With returns a Logger with the given attributes pre-attached. If Init() has not been called, returns a no-op Logger (writes to io.Discard).
Use for component-scoped loggers:
dbLog := logging.With("component", "database")
Source Files
Directories