8.1 KiB
API Reference
← Configuration | ← Back to README | Logging Guide →
Complete API documentation for the lixenwraith/log package.
Table of Contents
- Logger Creation
- Initialization Methods
- Logging Methods
- Trace Logging Methods
- Special Logging Methods
- Control Methods
- Constants
- Error Types
Logger Creation
NewLogger
func NewLogger() *Logger
Creates a new, uninitialized logger instance with default configuration parameters registered internally.
Example:
logger := log.NewLogger()
Initialization Methods
Init
func (l *Logger) Init(cfg *config.Config, basePath string) error
Initializes the logger using settings from a config.Config instance.
Parameters:
cfg: Configuration instance containing logger settingsbasePath: Prefix for configuration keys (e.g., "logging" looks for "logging.level", "logging.directory", etc.)
Returns:
error: Initialization error if configuration is invalid
Example:
cfg := config.New()
cfg.Load("app.toml", os.Args[1:])
err := logger.Init(cfg, "logging")
InitWithDefaults
func (l *Logger) InitWithDefaults(overrides ...string) error
Initializes the logger using built-in defaults with optional overrides.
Parameters:
overrides: Variable number of "key=value" strings
Returns:
error: Initialization error if overrides are invalid
Example:
err := logger.InitWithDefaults(
"directory=/var/log/app",
"level=-4",
"format=json",
)
LoadConfig
func (l *Logger) LoadConfig(path string, args []string) error
Loads configuration from a TOML file with CLI overrides.
Parameters:
path: Path to TOML configuration fileargs: Command-line arguments for overrides
Returns:
error: Load or initialization error
Example:
err := logger.LoadConfig("config.toml", os.Args[1:])
SaveConfig
func (l *Logger) SaveConfig(path string) error
Saves the current logger configuration to a file.
Parameters:
path: Path where configuration should be saved
Returns:
error: Save error if write fails
Example:
err := logger.SaveConfig("current-config.toml")
Logging Methods
All logging methods accept variadic arguments, typically used as key-value pairs for structured logging.
Debug
func (l *Logger) Debug(args ...any)
Logs a message at debug level (-4).
Example:
logger.Debug("Processing started", "items", 100, "mode", "batch")
Info
func (l *Logger) Info(args ...any)
Logs a message at info level (0).
Example:
logger.Info("Server started", "port", 8080, "tls", true)
Warn
func (l *Logger) Warn(args ...any)
Logs a message at warning level (4).
Example:
logger.Warn("High memory usage", "used_mb", 1800, "limit_mb", 2048)
Error
func (l *Logger) Error(args ...any)
Logs a message at error level (8).
Example:
logger.Error("Database connection failed", "host", "db.example.com", "error", err)
Trace Logging Methods
These methods include function call traces in the log output.
DebugTrace
func (l *Logger) DebugTrace(depth int, args ...any)
Logs at debug level with function call trace.
Parameters:
depth: Number of stack frames to include (0-10)args: Log message and fields
Example:
logger.DebugTrace(3, "Entering critical section", "mutex", "db_lock")
InfoTrace
func (l *Logger) InfoTrace(depth int, args ...any)
Logs at info level with function call trace.
WarnTrace
func (l *Logger) WarnTrace(depth int, args ...any)
Logs at warning level with function call trace.
ErrorTrace
func (l *Logger) ErrorTrace(depth int, args ...any)
Logs at error level with function call trace.
Special Logging Methods
Log
func (l *Logger) Log(args ...any)
Logs with timestamp only, no level information (uses Info level internally).
Example:
logger.Log("Checkpoint reached", "step", 5)
Message
func (l *Logger) Message(args ...any)
Logs raw message without timestamp or level.
Example:
logger.Message("Raw output for special formatting")
LogTrace
func (l *Logger) LogTrace(depth int, args ...any)
Logs with timestamp and trace, but no level information.
Example:
logger.LogTrace(2, "Function boundary", "entering", true)
Control Methods
Shutdown
func (l *Logger) Shutdown(timeout ...time.Duration) error
Gracefully shuts down the logger, attempting to flush pending logs.
Parameters:
timeout: Optional timeout duration (defaults to 2x flush interval)
Returns:
error: Shutdown error if flush fails or timeout exceeded
Example:
err := logger.Shutdown(5 * time.Second)
if err != nil {
fmt.Printf("Shutdown error: %v\n", err)
}
Flush
func (l *Logger) Flush(timeout time.Duration) error
Explicitly triggers a sync of the current log file buffer to disk.
Parameters:
timeout: Maximum time to wait for flush completion
Returns:
error: Flush error if timeout exceeded
Example:
err := logger.Flush(1 * time.Second)
Constants
Log Levels
const (
LevelDebug int64 = -4
LevelInfo int64 = 0
LevelWarn int64 = 4
LevelError int64 = 8
)
Standard log levels for filtering output.
Heartbeat Levels
const (
LevelProc int64 = 12 // Process statistics
LevelDisk int64 = 16 // Disk usage statistics
LevelSys int64 = 20 // System statistics
)
Special levels for heartbeat monitoring that bypass level filtering.
Format Flags
const (
FlagShowTimestamp int64 = 0b01
FlagShowLevel int64 = 0b10
FlagDefault = FlagShowTimestamp | FlagShowLevel
)
Flags controlling log entry format.
Level Helper Function
func Level(levelStr string) (int64, error)
Converts level string to numeric constant.
Parameters:
levelStr: Level name ("debug", "info", "warn", "error", "proc", "disk", "sys")
Returns:
int64: Numeric level valueerror: Conversion error for invalid strings
Example:
level, err := log.Level("debug") // Returns -4
Error Types
The logger returns errors prefixed with "log: " for easy identification:
// Configuration errors
"log: invalid format: 'xml' (use txt or json)"
"log: buffer_size must be positive: 0"
// Initialization errors
"log: failed to create log directory '/var/log/app': permission denied"
"log: logger previously failed to initialize and is disabled"
// Runtime errors
"log: logger not initialized or already shut down"
"log: timeout waiting for flush confirmation (1s)"
Thread Safety
All public methods are thread-safe and can be called concurrently from multiple goroutines. The logger uses atomic operations and channels to ensure safe concurrent access without locks in the critical path.
Usage Examples
Complete Service Example
type Service struct {
logger *log.Logger
}
func NewService() (*Service, error) {
logger := log.NewLogger()
err := logger.InitWithDefaults(
"directory=/var/log/service",
"format=json",
"buffer_size=2048",
"heartbeat_level=1",
)
if err != nil {
return nil, fmt.Errorf("logger init: %w", err)
}
return &Service{logger: logger}, nil
}
func (s *Service) ProcessRequest(id string) error {
s.logger.InfoTrace(1, "Processing request", "id", id)
if err := s.doWork(id); err != nil {
s.logger.Error("Request failed", "id", id, "error", err)
return err
}
s.logger.Info("Request completed", "id", id)
return nil
}
func (s *Service) Shutdown() error {
return s.logger.Shutdown(5 * time.Second)
}