log/doc/llm-guide.md

lixenwraith/log LLM Usage Guide

High-performance, thread-safe logging library for Go with file rotation, disk management, and compatibility adapters for popular frameworks.

Core Types

Logger

// Primary logger instance. All operations are thread-safe.
type Logger struct {
    // Internal fields - thread-safe logging implementation
}

Config

// Logger configuration with validation support.
type Config struct {
    // Basic settings
    Level     int64  `toml:"level"`
    Name      string `toml:"name"`
    Directory string `toml:"directory"`
    Format    string `toml:"format"`     // "txt", "json", or "raw"
    Extension string `toml:"extension"`

    // Formatting
    ShowTimestamp   bool   `toml:"show_timestamp"`
    ShowLevel       bool   `toml:"show_level"`
    TimestampFormat string `toml:"timestamp_format"`

    // Buffer and size limits
    BufferSize     int64 `toml:"buffer_size"`
    MaxSizeMB      int64 `toml:"max_size_mb"`
    MaxTotalSizeMB int64 `toml:"max_total_size_mb"`
    MinDiskFreeMB  int64 `toml:"min_disk_free_mb"`

    // Timers
    FlushIntervalMs    int64   `toml:"flush_interval_ms"`
    TraceDepth         int64   `toml:"trace_depth"`
    RetentionPeriodHrs float64 `toml:"retention_period_hrs"`
    RetentionCheckMins float64 `toml:"retention_check_mins"`

    // Disk check settings
    DiskCheckIntervalMs    int64 `toml:"disk_check_interval_ms"`
    EnableAdaptiveInterval bool  `toml:"enable_adaptive_interval"`
    EnablePeriodicSync     bool  `toml:"enable_periodic_sync"`
    MinCheckIntervalMs     int64 `toml:"min_check_interval_ms"`
    MaxCheckIntervalMs     int64 `toml:"max_check_interval_ms"`

    // Heartbeat configuration
    HeartbeatLevel     int64 `toml:"heartbeat_level"`
    HeartbeatIntervalS int64 `toml:"heartbeat_interval_s"`

    // Stdout/console output settings
    EnableStdout bool   `toml:"enable_stdout"`
    StdoutTarget string `toml:"stdout_target"` // "stdout", "stderr", or "split"
    DisableFile  bool   `toml:"disable_file"`

    // Internal error handling
    InternalErrorsToStderr bool `toml:"internal_errors_to_stderr"`
}

Constants

Log Levels

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

Heartbeat Levels

const (
    LevelProc int64 = 12  // Process statistics
    LevelDisk int64 = 16  // Disk usage statistics
    LevelSys  int64 = 20  // System statistics
)

Core Methods

Creation

func NewLogger() *Logger
func DefaultConfig() *Config

Configuration

func (l *Logger) ApplyConfig(cfg *Config) error
func (l *Logger) ApplyOverride(overrides ...string) error
func (l *Logger) GetConfig() *Config

Logging Methods

func (l *Logger) Debug(args ...any)
func (l *Logger) Info(args ...any)
func (l *Logger) Warn(args ...any)
func (l *Logger) Error(args ...any)
func (l *Logger) LogStructured(level int64, message string, fields map[string]any)
func (l *Logger) Write(args ...any)  // Raw output, no formatting
func (l *Logger) Log(args ...any)     // Timestamp only, no level
func (l *Logger) Message(args ...any) // No timestamp or level

Trace Logging

func (l *Logger) DebugTrace(depth int, args ...any)
func (l *Logger) InfoTrace(depth int, args ...any)
func (l *Logger) WarnTrace(depth int, args ...any)
func (l *Logger) ErrorTrace(depth int, args ...any)
func (l *Logger) LogTrace(depth int, args ...any)

Control Methods

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

Utilities

func Level(levelStr string) (int64, error)

Configuration Builder

ConfigBuilder

type ConfigBuilder struct {
    // Internal builder state
}

Builder Methods

func NewConfigBuilder() *ConfigBuilder
func (b *ConfigBuilder) Build() (*Config, error)
func (b *ConfigBuilder) Level(level int64) *ConfigBuilder
func (b *ConfigBuilder) LevelString(level string) *ConfigBuilder
func (b *ConfigBuilder) Directory(dir string) *ConfigBuilder
func (b *ConfigBuilder) Format(format string) *ConfigBuilder
func (b *ConfigBuilder) BufferSize(size int64) *ConfigBuilder
func (b *ConfigBuilder) MaxSizeMB(size int64) *ConfigBuilder
func (b *ConfigBuilder) EnableStdout(enable bool) *ConfigBuilder
func (b *ConfigBuilder) DisableFile(disable bool) *ConfigBuilder
func (b *ConfigBuilder) HeartbeatLevel(level int64) *ConfigBuilder
func (b *ConfigBuilder) HeartbeatIntervalS(seconds int64) *ConfigBuilder

Compatibility Adapters (log/compat)

Builder

type Builder struct {
    // Internal adapter builder state
}

Builder Methods

func NewBuilder() *Builder
func (b *Builder) WithLogger(l *log.Logger) *Builder
func (b *Builder) WithConfig(cfg *log.Config) *Builder
func (b *Builder) BuildGnet(opts ...GnetOption) (*GnetAdapter, error)
func (b *Builder) BuildStructuredGnet(opts ...GnetOption) (*StructuredGnetAdapter, error)
func (b *Builder) BuildFastHTTP(opts ...FastHTTPOption) (*FastHTTPAdapter, error)
func (b *Builder) GetLogger() (*log.Logger, error)

gnet Adapters

type GnetAdapter struct {
    // Implements gnet.Logger interface
}

type StructuredGnetAdapter struct {
    *GnetAdapter
    // Enhanced with field extraction
}

type GnetOption func(*GnetAdapter)
func WithFatalHandler(handler func(string)) GnetOption

gnet Interface Implementation

func (a *GnetAdapter) Debugf(format string, args ...any)
func (a *GnetAdapter) Infof(format string, args ...any)
func (a *GnetAdapter) Warnf(format string, args ...any)
func (a *GnetAdapter) Errorf(format string, args ...any)
func (a *GnetAdapter) Fatalf(format string, args ...any)

fasthttp Adapter

type FastHTTPAdapter struct {
    // Implements fasthttp.Logger interface
}

type FastHTTPOption func(*FastHTTPAdapter)
func WithDefaultLevel(level int64) FastHTTPOption
func WithLevelDetector(detector func(string) int64) FastHTTPOption

fasthttp Interface Implementation

func (a *FastHTTPAdapter) Printf(format string, args ...any)

Helper Functions

func NewGnetAdapter(logger *log.Logger, opts ...GnetOption) *GnetAdapter
func NewStructuredGnetAdapter(logger *log.Logger, opts ...GnetOption) *StructuredGnetAdapter
func NewFastHTTPAdapter(logger *log.Logger, opts ...FastHTTPOption) *FastHTTPAdapter
func DetectLogLevel(msg string) int64

File Management

Rotation

Files rotate automatically when MaxSizeMB is reached. Rotated files use naming pattern: {name}_{YYMMDD}_{HHMMSS}_{nanoseconds}.{extension}

Disk Management

• Enforces MaxTotalSizeMB for total log directory size
• Maintains MinDiskFreeMB free disk space
• Deletes oldest logs when limits exceeded

Retention

• Time-based cleanup with RetentionPeriodHrs
• Periodic checks via RetentionCheckMins

Heartbeat Monitoring

Levels

• 0: Disabled (default)
• 1: Process stats (logs processed, dropped, uptime)
• 2: + Disk stats (rotations, deletions, sizes, free space)
• 3: + System stats (memory, GC, goroutines)

Output

Heartbeats bypass log level filtering and use special levels (PROC, DISK, SYS).

Output Formats

Text Format

Human-readable with configurable timestamp and level display.

JSON Format

Machine-parseable with structured fields array.

Raw Format

Space-separated values without metadata, triggered by Write() method or format=raw.

Thread Safety

All public methods are thread-safe. Concurrent logging from multiple goroutines is supported without external synchronization.

Configuration Overrides

String key-value pairs for runtime configuration changes:

"level=-4"              // Numeric level
"level=debug"           // Named level
"directory=/var/log"    // String value
"buffer_size=2048"      // Integer value
"enable_stdout=true"    // Boolean value

Error Handling

• Configuration errors prefixed with "log: "
• Failed initialization disables logger
• Dropped logs tracked and reported periodically
• Internal errors optionally written to stderr

Performance Characteristics

• Non-blocking log submission (buffered channel)
• Adaptive disk checking based on load
• Batch file writes with configurable flush interval
• Automatic log dropping under extreme load with tracking