e2.0.0 Init and config pattern changed, builder added, docs updated, examples removed (deprecated).
This commit is contained in:
284
doc/llm-guide.md
Normal file
284
doc/llm-guide.md
Normal file
@ -0,0 +1,284 @@
|
||||
# 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
|
||||
```go
|
||||
// Primary logger instance. All operations are thread-safe.
|
||||
type Logger struct {
|
||||
// Internal fields - thread-safe logging implementation
|
||||
}
|
||||
```
|
||||
|
||||
### Config
|
||||
```go
|
||||
// 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
|
||||
```go
|
||||
const (
|
||||
LevelDebug int64 = -4
|
||||
LevelInfo int64 = 0
|
||||
LevelWarn int64 = 4
|
||||
LevelError int64 = 8
|
||||
)
|
||||
```
|
||||
|
||||
### Heartbeat Levels
|
||||
```go
|
||||
const (
|
||||
LevelProc int64 = 12 // Process statistics
|
||||
LevelDisk int64 = 16 // Disk usage statistics
|
||||
LevelSys int64 = 20 // System statistics
|
||||
)
|
||||
```
|
||||
|
||||
## Core Methods
|
||||
|
||||
### Creation
|
||||
```go
|
||||
func NewLogger() *Logger
|
||||
func DefaultConfig() *Config
|
||||
```
|
||||
|
||||
### Configuration
|
||||
```go
|
||||
func (l *Logger) ApplyConfig(cfg *Config) error
|
||||
func (l *Logger) ApplyOverride(overrides ...string) error
|
||||
func (l *Logger) GetConfig() *Config
|
||||
```
|
||||
|
||||
### Logging Methods
|
||||
```go
|
||||
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
|
||||
```go
|
||||
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
|
||||
```go
|
||||
func (l *Logger) Shutdown(timeout ...time.Duration) error
|
||||
func (l *Logger) Flush(timeout time.Duration) error
|
||||
```
|
||||
|
||||
### Utilities
|
||||
```go
|
||||
func Level(levelStr string) (int64, error)
|
||||
```
|
||||
|
||||
## Configuration Builder
|
||||
|
||||
### ConfigBuilder
|
||||
```go
|
||||
type ConfigBuilder struct {
|
||||
// Internal builder state
|
||||
}
|
||||
```
|
||||
|
||||
### Builder Methods
|
||||
```go
|
||||
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
|
||||
```go
|
||||
type Builder struct {
|
||||
// Internal adapter builder state
|
||||
}
|
||||
```
|
||||
|
||||
### Builder Methods
|
||||
```go
|
||||
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
|
||||
```go
|
||||
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
|
||||
```go
|
||||
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
|
||||
```go
|
||||
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
|
||||
```go
|
||||
func (a *FastHTTPAdapter) Printf(format string, args ...any)
|
||||
```
|
||||
|
||||
### Helper Functions
|
||||
```go
|
||||
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
|
||||
Reference in New Issue
Block a user