log

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 11, 2025 License: BSD-3-Clause Imports: 18 Imported by: 0

README

Log

Go License Documentation

A high-performance, buffered, rotating file logger for Go applications with built-in disk management, operational monitoring, and framework compatibility adapters.

Key Features

  • Lock-free async logging with minimal application impact
  • Automatic file rotation and disk space management
  • Operational heartbeats for production monitoring
  • Hot reconfiguration without data loss
  • Framework adapters for gnet v2 and fasthttp
  • Production-grade reliability with graceful shutdown

Quick Start

package main

import (
	"fmt"
	
    "github.com/lixenwraith/log"
)

func main() {
    // Create and initialize logger
    logger := log.NewLogger()
    err := logger.ApplyConfigString("directory=/var/log/myapp")
    if err != nil {
        panic(fmt.Errorf("failed to apply logger config: %w", err))
    }
    defer logger.Shutdown()

    // Start logging
	if err = logger.Start(); err != nil {
        panic(fmt.Errorf("failed to start logger: %w", err))
    }
    logger.Info("Application started", "version", "1.0.0")
    logger.Debug("Debug information", "user_id", 12345)
    logger.Warn("Warning message", "threshold", 0.95)
    logger.Error("Error occurred", "code", 500)
}

Installation

go get github.com/lixenwraith/log

For configuration management support:

go get github.com/lixenwraith/config

Documentation

Architecture Overview

The logger uses a lock-free, channel-based architecture for high performance:

Application → Log Methods → Buffered Channel → Background Processor → File/Console
                ↓                                      ↓
            (non-blocking)                    (rotation, cleanup, monitoring)

Contributing

Contributions and suggestions are welcome! There is no contribution policy, but if interested, please submit pull requests to the repository. Submit suggestions or issues at issue tracker.

License

BSD-3-Clause

Documentation

Overview

FILE: lixenwraith/log/builder.go

FILE: lixenwraith/log/config.go

FILE: lixenwraith/log/constant.go

FILE: lixenwraith/log/format.go

FILE: lixenwraith/log/heartbeat.go

FILE: lixenwraith/log/logger.go

FILE: lixenwraith/log/processor.go

FILE: lixenwraith/log/record.go

FILE: lixenwraith/log/state.go

FILE: lixenwraith/log/storage.go

FILE: lixenwraith/log/processor.go

FILE: lixenwraith/log/type.go

FILE: lixenwraith/log/utility.go

Index

Constants

View Source 
const (
	LevelDebug int64 = -4
	LevelInfo  int64 = 0
	LevelWarn  int64 = 4
	LevelError int64 = 8
)

Log level constants

View Source 
const (
	LevelProc int64 = 12
	LevelDisk int64 = 16
	LevelSys  int64 = 20
)

Heartbeat log levels

View Source 
const (
	FlagShowTimestamp  int64 = 0b0001
	FlagShowLevel      int64 = 0b0010
	FlagRaw            int64 = 0b0100
	FlagStructuredJSON int64 = 0b1000
	FlagDefault              = FlagShowTimestamp | FlagShowLevel
)

Record flags for controlling output structure

Variables

This section is empty.

Functions

func Level 

func Level(levelStr string) (int64, error)

Level converts level string to numeric constant

Types

type Builder 

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

Builder provides a fluent API for building logger configurations It wraps a Config instance and provides chainable methods for setting values

func NewBuilder 

func NewBuilder() *Builder

NewBuilder creates a new configuration builder with default values

func (*Builder) BufferSize 

func (b *Builder) BufferSize(size int64) *Builder

BufferSize sets the channel buffer size

func (*Builder) Build 

func (b *Builder) Build() (*Logger, error)

Build creates a new Logger instance with the specified configuration

func (*Builder) ConsoleTarget 

func (b *Builder) ConsoleTarget(target string) *Builder

ConsoleTarget sets the console output target ("stdout", "stderr", or "split")

func (*Builder) Directory 

func (b *Builder) Directory(dir string) *Builder

Directory sets the log directory

func (*Builder) DiskCheckIntervalMs 

func (b *Builder) DiskCheckIntervalMs(interval int64) *Builder

DiskCheckIntervalMs sets the disk check interval in milliseconds

func (*Builder) EnableAdaptiveInterval 

func (b *Builder) EnableAdaptiveInterval(enable bool) *Builder

EnableAdaptiveInterval enables adaptive disk check intervals

func (*Builder) EnableConsole 

func (b *Builder) EnableConsole(enable bool) *Builder

EnableConsole enables console output

func (*Builder) EnableFile 

func (b *Builder) EnableFile(enable bool) *Builder

EnableFile enables file output

func (*Builder) EnablePeriodicSync 

func (b *Builder) EnablePeriodicSync(enable bool) *Builder

EnablePeriodicSync enables periodic file sync

func (*Builder) Extension 

func (b *Builder) Extension(ext string) *Builder

Extension sets the log level

func (*Builder) FlushIntervalMs 

func (b *Builder) FlushIntervalMs(interval int64) *Builder

FlushIntervalMs sets the flush interval in milliseconds

func (*Builder) Format 

func (b *Builder) Format(format string) *Builder

Format sets the output format

func (*Builder) HeartbeatIntervalS 

func (b *Builder) HeartbeatIntervalS(interval int64) *Builder

HeartbeatIntervalS sets the heartbeat monitoring level

func (*Builder) HeartbeatLevel 

func (b *Builder) HeartbeatLevel(level int64) *Builder

HeartbeatLevel sets the heartbeat monitoring level

func (*Builder) InternalErrorsToStderr 

func (b *Builder) InternalErrorsToStderr(enable bool) *Builder

InternalErrorsToStderr sets whether to write internal errors to stderr

func (*Builder) Level 

func (b *Builder) Level(level int64) *Builder

Level sets the log level

func (*Builder) LevelString 

func (b *Builder) LevelString(level string) *Builder

LevelString sets the log level from a string

func (*Builder) MaxCheckIntervalMs 

func (b *Builder) MaxCheckIntervalMs(interval int64) *Builder

MaxCheckIntervalMs sets the maximum disk check interval in milliseconds

func (*Builder) MaxSizeKB 

func (b *Builder) MaxSizeKB(size int64) *Builder

MaxSizeKB sets the maximum log file size in KB

func (*Builder) MaxSizeMB 

func (b *Builder) MaxSizeMB(size int64) *Builder

MaxSizeMB sets the maximum log file size in MB

func (*Builder) MaxTotalSizeKB 

func (b *Builder) MaxTotalSizeKB(size int64) *Builder

MaxTotalSizeKB sets the maximum total size of all log files in KB

func (*Builder) MaxTotalSizeMB 

func (b *Builder) MaxTotalSizeMB(size int64) *Builder

MaxTotalSizeMB sets the maximum total size of all log files in MB

func (*Builder) MinCheckIntervalMs 

func (b *Builder) MinCheckIntervalMs(interval int64) *Builder

MinCheckIntervalMs sets the minimum disk check interval in milliseconds

func (*Builder) MinDiskFreeKB 

func (b *Builder) MinDiskFreeKB(size int64) *Builder

MinDiskFreeKB sets the minimum required free disk space in KB

func (*Builder) MinDiskFreeMB 

func (b *Builder) MinDiskFreeMB(size int64) *Builder

MinDiskFreeMB sets the minimum required free disk space in MB

func (*Builder) Name 

func (b *Builder) Name(name string) *Builder

Name sets the log level

func (*Builder) RetentionCheckMins 

func (b *Builder) RetentionCheckMins(mins float64) *Builder

RetentionCheckMins sets the retention check interval in minutes

func (*Builder) RetentionPeriodHrs 

func (b *Builder) RetentionPeriodHrs(hours float64) *Builder

RetentionPeriodHrs sets the log retention period in hours

func (*Builder) ShowLevel 

func (b *Builder) ShowLevel(show bool) *Builder

ShowLevel sets whether to show log levels

func (*Builder) ShowTimestamp 

func (b *Builder) ShowTimestamp(show bool) *Builder

ShowTimestamp sets whether to show timestamps in logs

func (*Builder) TimestampFormat 

func (b *Builder) TimestampFormat(format string) *Builder

TimestampFormat sets the timestamp format string

func (*Builder) TraceDepth 

func (b *Builder) TraceDepth(depth int64) *Builder

TraceDepth sets the default trace depth for stack traces

type Config 

type Config struct {
	// File and Console output settings
	EnableConsole bool   `toml:"enable_console"` // Enable console output (stdout/stderr)
	ConsoleTarget string `toml:"console_target"` // "stdout", "stderr", or "split"
	EnableFile    bool   `toml:"enable_file"`    // Enable file output

	// Basic settings
	Level     int64  `toml:"level"`     // Log records at or above this Level will be logged
	Name      string `toml:"name"`      // Base name for log files
	Directory string `toml:"directory"` // Directory for log files
	Format    string `toml:"format"`    // "txt", "raw", or "json"
	Extension string `toml:"extension"` // Log file extension

	// Formatting
	ShowTimestamp   bool   `toml:"show_timestamp"`   // Add timestamp to log records
	ShowLevel       bool   `toml:"show_level"`       // Add level to log record
	TimestampFormat string `toml:"timestamp_format"` // Time format for log timestamps

	// Buffer and size limits
	BufferSize     int64 `toml:"buffer_size"`       // Channel buffer size
	MaxSizeKB      int64 `toml:"max_size_kb"`       // Max size per log file
	MaxTotalSizeKB int64 `toml:"max_total_size_kb"` // Max total size of all logs in dir
	MinDiskFreeKB  int64 `toml:"min_disk_free_kb"`  // Minimum free disk space required

	// Timers
	FlushIntervalMs    int64   `toml:"flush_interval_ms"`    // Interval for flushing file buffer
	TraceDepth         int64   `toml:"trace_depth"`          // Default trace depth (0-10)
	RetentionPeriodHrs float64 `toml:"retention_period_hrs"` // Hours to keep logs (0=disabled)
	RetentionCheckMins float64 `toml:"retention_check_mins"` // How often to check retention

	// Disk check settings
	DiskCheckIntervalMs    int64 `toml:"disk_check_interval_ms"`   // Base interval for disk checks
	EnableAdaptiveInterval bool  `toml:"enable_adaptive_interval"` // Adjust interval based on log rate
	EnablePeriodicSync     bool  `toml:"enable_periodic_sync"`     // Periodic sync with disk
	MinCheckIntervalMs     int64 `toml:"min_check_interval_ms"`    // Minimum adaptive interval
	MaxCheckIntervalMs     int64 `toml:"max_check_interval_ms"`    // Maximum adaptive interval

	// Heartbeat configuration
	HeartbeatLevel     int64 `toml:"heartbeat_level"`      // 0=disabled, 1=proc only, 2=proc+disk, 3=proc+disk+sys
	HeartbeatIntervalS int64 `toml:"heartbeat_interval_s"` // Interval seconds for heartbeat

	// Internal error handling
	InternalErrorsToStderr bool `toml:"internal_errors_to_stderr"` // Write internal errors to stderr
}

Config holds all logger configuration values

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a copy of the default configuration

func (*Config) Clone 

func (c *Config) Clone() *Config

Clone creates a deep copy of the configuration

func (*Config) Validate 

func (c *Config) Validate() error

Validate performs validation on the configuration

type Logger 

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

Logger is the core struct that encapsulates all logger functionality

func NewLogger 

func NewLogger() *Logger

NewLogger creates a new Logger instance with default settings

func (*Logger) ApplyConfig 

func (l *Logger) ApplyConfig(cfg *Config) error

ApplyConfig applies a validated configuration to the logger This is the primary way applications should configure the logger

func (*Logger) ApplyConfigString 

func (l *Logger) ApplyConfigString(overrides ...string) error

ApplyConfigString applies string key-value overrides to the logger's current configuration Each override should be in the format "key=value"

func (*Logger) Debug 

func (l *Logger) Debug(args ...any)

Debug logs a message at debug level

func (*Logger) DebugTrace 

func (l *Logger) DebugTrace(depth int, args ...any)

DebugTrace logs a debug message with function call trace

func (*Logger) Error 

func (l *Logger) Error(args ...any)

Error logs a message at error level

func (*Logger) ErrorTrace 

func (l *Logger) ErrorTrace(depth int, args ...any)

ErrorTrace logs an error message with function call trace

func (*Logger) Flush 

func (l *Logger) Flush(timeout time.Duration) error

Flush explicitly triggers a sync of the current log file buffer to disk and waits for completion or timeout

func (*Logger) GetConfig 

func (l *Logger) GetConfig() *Config

GetConfig returns a copy of current configuration

func (*Logger) Info 

func (l *Logger) Info(args ...any)

Info logs a message at info level

func (*Logger) InfoTrace 

func (l *Logger) InfoTrace(depth int, args ...any)

InfoTrace logs an info message with function call trace

func (*Logger) Log 

func (l *Logger) Log(args ...any)

Log writes a timestamp-only record without level information

func (*Logger) LogStructured 

func (l *Logger) LogStructured(level int64, message string, fields map[string]any)

LogStructured logs a message with structured fields as proper JSON

func (*Logger) LogTrace 

func (l *Logger) LogTrace(depth int, args ...any)

LogTrace writes a timestamp record with call trace but no level info

func (*Logger) Message 

func (l *Logger) Message(args ...any)

Message writes a plain record without timestamp or level info

func (*Logger) Shutdown 

func (l *Logger) Shutdown(timeout ...time.Duration) error

Shutdown gracefully closes the logger, attempting to flush pending records If no timeout is provided, uses a default of 2x flush interval

func (*Logger) Start 

func (l *Logger) Start() error

Start begins log processing. Safe to call multiple times Returns error if logger is not initialized

func (*Logger) Stop 

func (l *Logger) Stop(timeout ...time.Duration) error

Stop halts log processing. Can be restarted with Start() Returns nil if already stopped

func (*Logger) Warn 

func (l *Logger) Warn(args ...any)

Warn logs a message at warning level

func (*Logger) WarnTrace 

func (l *Logger) WarnTrace(depth int, args ...any)

WarnTrace logs a warning message with function call trace

func (*Logger) Write 

func (l *Logger) Write(args ...any)

Write outputs raw, unformatted data regardless of configured format Writes args as space-separated strings without a trailing newline

type State 

type State struct {
	// General state
	IsInitialized   atomic.Bool // Tracks successful initialization, not start of log processor
	LoggerDisabled  atomic.Bool // Tracks logger stop due to issues (e.g. disk full)
	ShutdownCalled  atomic.Bool // Tracks if Shutdown() has been called, a terminal state
	DiskFullLogged  atomic.Bool // Tracks if a disk full error has been logged to prevent log spam
	DiskStatusOK    atomic.Bool // Tracks if disk space and size limits are currently met
	Started         atomic.Bool // Tracks calls to Start() and Stop()
	ProcessorExited atomic.Bool // Tracks if the processor goroutine is running or has exited

	// Outputs
	CurrentFile  atomic.Value // stores *os.File
	StdoutWriter atomic.Value // stores io.Writer (os.Stdout, os.Stderr, or io.Discard)

	// File State
	CurrentSize      atomic.Int64 // Size of the current log file
	EarliestFileTime atomic.Value // stores time.Time for retention

	// Log state
	ActiveLogChannel atomic.Value  // stores chan logRecord
	DroppedLogs      atomic.Uint64 // Counter for logs dropped since last heartbeat
	TotalDroppedLogs atomic.Uint64 // Counter for total logs dropped since logger start

	// Heartbeat statistics
	HeartbeatSequence  atomic.Uint64 // Counter for heartbeat sequence numbers
	LoggerStartTime    atomic.Value  // Stores time.Time for uptime calculation
	TotalLogsProcessed atomic.Uint64 // Counter for non-heartbeat logs successfully processed
	TotalRotations     atomic.Uint64 // Counter for successful log rotations
	TotalDeletions     atomic.Uint64 // Counter for successful log deletions (cleanup/retention)
	// contains filtered or unexported fields
}

State encapsulates the runtime state of the logger

type TimerSet 

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

TimerSet holds all timers used in processLogs

Source Files

View all Source files

Directories

Path Synopsis
FILE: lixenwraith/log/compat/builder.go
 FILE: lixenwraith/log/compat/builder.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.