Documentation
¶
Overview ¶
Package gourdianlogger provides a high-performance, feature-rich logging solution for Go.
Overview: GourdianLogger is designed for production systems requiring robust, configurable logging with minimal performance impact. It combines traditional logging with modern features like structured logging, rate limiting, and dynamic level control.
Key Features: - Multiple log levels (DEBUG, INFO, WARN, ERROR, FATAL) - Plain text and JSON output formats - Structured logging with arbitrary fields - Asynchronous logging with configurable buffer and workers - Size-based log rotation - Rate limiting - Caller information (file:line:function) - Fallback mechanisms - Thread-safe operations
Getting Started:
Basic example:
package main
import (
"github.com/your/module/gourdianlogger"
)
func main() {
// Create logger with default configuration
logger, err := gourdianlogger.NewDefaultGourdianLogger()
if err != nil {
panic(err)
}
defer logger.Close() // Important for flushing buffers
logger.Info("Application starting")
logger.Debug("Initialization complete")
}
Configuration:
The logger can be configured either programmatically:
config := gourdianlogger.LoggerConfig{
Filename: "myapp",
LogLevel: gourdianlogger.INFO,
LogFormat: gourdianlogger.FormatJSON,
MaxBytes: 10 * 1024 * 1024, // 10MB
BackupCount: 5,
BufferSize: 1000, // Async buffer size
AsyncWorkers: 4, // Number of async workers
MaxLogRate: 1000, // Max logs per second
EnableCaller: true, // Include caller info
EnableFallback: true, // Fallback to stderr on errors
}
logger, err := gourdianlogger.NewGourdianLogger(config)
Log Levels:
Log levels control message verbosity. Messages below the configured level are ignored. Level order: DEBUG < INFO < WARN < ERROR < FATAL
Example level usage:
logger.SetLogLevel(gourdianlogger.WARN) // Only WARN and above
logger.Debug("This won't appear") // Below current level
logger.Error("This will appear") // Above current level
Dynamic Level Control:
logger.SetDynamicLevelFunc(func() gourdianlogger.LogLevel {
if debugMode {
return gourdianlogger.DEBUG
}
return gourdianlogger.INFO
})
Output Formats:
Two formats are supported: - FormatPlain: Human-readable text (default) - FormatJSON: Structured JSON output
Format comparison:
Plain: 2025-04-19 10:00:00.000000 INFO main.go:42:main Server started on port 8080
JSON:
{
"timestamp": "2025-04-19 10:00:00.000000",
"level": "INFO",
"message": "Server started on port 8080",
"caller": "main.go:42:main"
}
Structured Logging:
Add contextual fields to log messages:
logger.InfofWithFields(map[string]interface{}{
"user_id": 123,
"duration": 45.2,
"endpoint": "/api/user",
}, "Request processed")
Outputs (JSON):
{
"timestamp": "...",
"level": "INFO",
"message": "Request processed",
"user_id": 123,
"duration": 45.2,
"endpoint": "/api/user"
}
Log Rotation:
Logs are rotated when they exceed MaxBytes. Old logs are kept according to BackupCount.
Rotation example:
config := gourdianlogger.LoggerConfig{
MaxBytes: 50 * 1024 * 1024, // 50MB
BackupCount: 5, // Keep 5 backups
}
Creates files like: - myapp.log (current) - myapp_20250419_000000.log (rotated) - myapp_20250418_000000.log (rotated)
Asynchronous Logging:
For high-throughput systems, enable async logging:
config := gourdianlogger.LoggerConfig{
BufferSize: 1000, // Buffer capacity
AsyncWorkers: 4, // Parallel workers
}
Important: Call logger.Flush() before shutdown to ensure all logs are written.
Rate Limiting:
config.MaxLogRate = 100 // Max 100 logs/second
Messages exceeding the rate limit are silently dropped.
Error Handling:
Custom error handling can be configured:
config.ErrorHandler = func(err error) {
sentry.CaptureException(err)
fmt.Fprintf(os.Stderr, "LOGGER ERROR: %v\n", err)
}
Fallback Mechanism:
When enabled (default), failed log writes will attempt to write to stderr: FALLBACK LOG: [message content]
Pausing Logging:
Temporarily pause logging during critical sections:
logger.Pause() defer logger.Resume() // Critical section
Testing:
For testing, you may want to: - Disable file output - Use a buffer for verification - Set synchronous logging
Test configuration example:
func TestLogger(t *testing.T) {
var buf bytes.Buffer
config := gourdianlogger.LoggerConfig{
Outputs: []io.Writer{&buf},
BufferSize: 0, // Synchronous for testing
EnableCaller: false,
}
logger, _ := gourdianlogger.NewGourdianLogger(config)
logger.Info("Test message")
assert.Contains(t, buf.String(), "Test message")
}
Best Practices: 1. Always defer logger.Close() 2. For async logging, ensure proper buffer sizing 3. Set appropriate log levels in production 4. Use structured logging for machine-readable logs 5. Monitor log rotation in high-volume systems 6. Consider rate limiting for high-frequency debug logs
Performance Notes: - JSON formatting has ~10-15% overhead vs plain text - Async logging reduces latency but increases memory usage - Caller information adds minor overhead - Structured fields require additional allocations - Rate limiting adds minimal overhead when not active
Index ¶
- Variables
- type LogFormat
- type LogLevel
- type Logger
- func (l *Logger) AddOutput(output io.Writer)
- func (l *Logger) Close() error
- func (l *Logger) Debug(v ...interface{})
- func (l *Logger) DebugWithFields(fields map[string]interface{}, v ...interface{})
- func (l *Logger) Debugf(format string, v ...interface{})
- func (l *Logger) DebugfWithFields(fields map[string]interface{}, format string, v ...interface{})
- func (l *Logger) Error(v ...interface{})
- func (l *Logger) ErrorWithFields(fields map[string]interface{}, v ...interface{})
- func (l *Logger) Errorf(format string, v ...interface{})
- func (l *Logger) ErrorfWithFields(fields map[string]interface{}, format string, v ...interface{})
- func (l *Logger) Fatal(v ...interface{})
- func (l *Logger) FatalWithFields(fields map[string]interface{}, v ...interface{})
- func (l *Logger) Fatalf(format string, v ...interface{})
- func (l *Logger) FatalfWithFields(fields map[string]interface{}, format string, v ...interface{})
- func (l *Logger) Flush()
- func (l *Logger) GetLogLevel() LogLevel
- func (l *Logger) Info(v ...interface{})
- func (l *Logger) InfoWithFields(fields map[string]interface{}, v ...interface{})
- func (l *Logger) Infof(format string, v ...interface{})
- func (l *Logger) InfofWithFields(fields map[string]interface{}, format string, v ...interface{})
- func (l *Logger) IsClosed() bool
- func (l *Logger) IsPaused() bool
- func (l *Logger) Pause()
- func (l *Logger) RemoveOutput(output io.Writer)
- func (l *Logger) Resume()
- func (l *Logger) SetDynamicLevelFunc(fn func() LogLevel)
- func (l *Logger) SetLogLevel(level LogLevel)
- func (l *Logger) Warn(v ...interface{})
- func (l *Logger) WarnWithFields(fields map[string]interface{}, v ...interface{})
- func (l *Logger) Warnf(format string, v ...interface{})
- func (l *Logger) WarnfWithFields(fields map[string]interface{}, format string, v ...interface{})
- type LoggerConfig
Constants ¶
This section is empty.
Variables ¶
var Version = "v0.0.7"
Functions ¶
This section is empty.
Types ¶
type LogFormat ¶
type LogFormat int
LogFormat represents the format in which logs will be written.
const ( FormatPlain LogFormat = iota // Plain text format (human-readable) FormatJSON // JSON format (machine-readable) )
Constants defining available log formats.
func ParseLogFormat ¶ added in v0.0.7
ParseLogFormat converts a string representation of a log format to a LogFormat constant. Valid strings (case-insensitive): "PLAIN", "JSON".
type LogLevel ¶
type LogLevel int32
LogLevel represents the severity level of a log message. The levels are ordered from least to most severe: DEBUG < INFO < WARN < ERROR < FATAL.
const ( DEBUG LogLevel = iota // Debug-level messages for development INFO // Informational messages about normal operation WARN // Warning messages about potential issues ERROR // Error messages about problems that need attention FATAL // Fatal messages about critical errors that force shutdown )
Constants defining the available log levels.
func ParseLogLevel ¶
ParseLogLevel converts a string representation of a log level to a LogLevel constant. Valid strings (case-insensitive): "DEBUG", "INFO", "WARN"/"WARNING", "ERROR", "FATAL".
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger is the main logging struct that provides all logging functionality. It should be created using NewGourdianLogger() or NewDefaultGourdianLogger().
func NewDefaultGourdianLogger ¶ added in v0.0.3
NewDefaultGourdianLogger creates a new Logger with all default settings. This is the quickest way to get started with basic logging functionality.
Default configuration:
- Logs to "logs/gourdianlogs.log"
- 10MB file rotation
- Keeps 5 backup logs
- DEBUG level logging
- Plain text format
- Includes caller information
- Synchronous logging (no buffering)
- Falls back to stderr on errors
- No rate limiting
Example:
// Simple usage with defaults:
logger, err := gourdianlogger.NewDefaultGourdianLogger()
if err != nil {
panic(fmt.Errorf("failed to create logger: %w", err))
}
defer logger.Close()
// Basic logging:
logger.Debug("Debug message") // Will be logged
logger.Info("Informational message")
logger.Warn("Warning message")
logger.Error("Error message")
// Formatted logging:
logger.Infof("User %s logged in at %v", "john", time.Now())
// With fields (structured logging):
logger.InfoWithFields(map[string]interface{}{
"user": "john",
"ip": "192.168.1.1",
}, "User login")
Note: Remember to call Close() when done to ensure all logs are flushed and resources are properly released.
func NewGourdianLogger ¶
func NewGourdianLogger(config LoggerConfig) (*Logger, error)
NewGourdianLogger creates a new Logger with the specified configuration. The configuration is validated and sensible defaults are applied for any missing values.
Default values used when not specified in config:
- Filename: "gourdianlogs" (without .log extension)
- MaxBytes: 10MB (10 * 1024 * 1024)
- BackupCount: 5 (keep 5 rotated log files)
- LogLevel: DEBUG (log all levels)
- TimestampFormat: "2006-01-02 15:04:05.000000" (microsecond precision)
- LogsDir: "logs" (directory where log files are stored)
- EnableCaller: true (include caller information)
- BufferSize: 0 (synchronous logging)
- AsyncWorkers: 1 (if BufferSize > 0)
- LogFormat: FormatPlain (plain text format)
- EnableFallback: true (fallback to stderr on errors)
- MaxLogRate: 0 (no rate limiting)
The function performs the following operations:
- Validates the configuration
- Applies defaults for missing values
- Creates the log directory if it doesn't exist
- Opens/Creates the log file
- Initializes all logger components
- Starts background workers if needed
Example with custom configuration:
config := gourdianlogger.LoggerConfig{
Filename: "myapp", // Creates myapp.log
LogsDir: "var/logs", // Stores logs in var/logs/
MaxBytes: 20 * 1024 * 1024, // 20MB rotation size
BackupCount: 10, // Keep 10 rotated logs
LogLevel: gourdianlogger.INFO, // Only log INFO and above
AsyncWorkers: 4, // Use 4 async workers
BufferSize: 1000, // Buffer up to 1000 messages
EnableCaller: false, // Disable caller info
LogFormat: gourdianlogger.FormatJSON, // JSON format
MaxLogRate: 1000, // Limit to 1000 logs/second
CustomFields: map[string]interface{}{
"app": "myapp",
"version": "1.0.0",
},
}
logger, err := gourdianlogger.NewGourdianLogger(config)
if err != nil {
panic(fmt.Errorf("failed to create logger: %w", err))
}
defer logger.Close()
// Usage:
logger.Info("Application started")
logger.Debugf("Config loaded: %+v", config) // Won't be logged due to INFO level
func (*Logger) AddOutput ¶
AddOutput adds an additional io.Writer destination for log messages. Useful for sending logs to multiple destinations (e.g., file and network).
Example:
file, _ := os.Create("additional.log")
logger.AddOutput(file)
func (*Logger) Close ¶
Close cleanly shuts down the logger, flushing any buffered messages and closing open files. Should be called before program exit.
Example:
defer logger.Close()
func (*Logger) Debug ¶
func (l *Logger) Debug(v ...interface{})
Debug logs a message at DEBUG level. Arguments are handled like fmt.Sprint().
Example:
logger.Debug("Current value:", value)
func (*Logger) DebugWithFields ¶
DebugWithFields logs a message at DEBUG level with additional structured fields. Fields will be included in JSON output or as key-value pairs in text output.
Example:
logger.DebugWithFields(map[string]interface{}{
"user": username,
"attempt": 3,
}, "Login attempt")
func (*Logger) Debugf ¶
Debugf logs a formatted message at DEBUG level. Arguments are handled like fmt.Sprintf().
Example:
logger.Debugf("User %s logged in from %s", user, ip)
func (*Logger) DebugfWithFields ¶
DebugfWithFields logs a formatted message at DEBUG level with additional structured fields.
Example:
logger.DebugfWithFields(map[string]interface{}{
"duration": dur,
}, "Process took %.2f seconds", dur.Seconds())
func (*Logger) Error ¶
func (l *Logger) Error(v ...interface{})
Error logs a message at ERROR level. Arguments are handled like fmt.Sprint().
func (*Logger) ErrorWithFields ¶
ErrorWithFields logs a message at ERROR level with additional structured fields.
func (*Logger) Errorf ¶
Errorf logs a formatted message at ERROR level. Arguments are handled like fmt.Sprintf().
func (*Logger) ErrorfWithFields ¶
ErrorfWithFields logs a formatted message at ERROR level with additional structured fields.
func (*Logger) Fatal ¶
func (l *Logger) Fatal(v ...interface{})
Fatal logs a message at FATAL level and exits the program with status 1. Arguments are handled like fmt.Sprint().
func (*Logger) FatalWithFields ¶
FatalWithFields logs a message at FATAL level with additional structured fields and exits the program with status 1.
func (*Logger) Fatalf ¶
Fatalf logs a formatted message at FATAL level and exits the program with status 1. Arguments are handled like fmt.Sprintf().
func (*Logger) FatalfWithFields ¶
FatalfWithFields logs a formatted message at FATAL level with additional structured fields and exits the program with status 1.
func (*Logger) Flush ¶
func (l *Logger) Flush()
Flush ensures all buffered log messages are written to their destinations. This is particularly important for asynchronous logging to ensure messages are written before program exit.
Example:
logger.Info("Important message")
logger.Flush() // Ensure message is written before proceeding
func (*Logger) GetLogLevel ¶
GetLogLevel returns the current minimum log level.
Example:
if logger.GetLogLevel() <= gourdianlogger.DEBUG {
logger.Debug("Debug message")
}
func (*Logger) Info ¶
func (l *Logger) Info(v ...interface{})
Info logs a message at INFO level. Arguments are handled like fmt.Sprint().
func (*Logger) InfoWithFields ¶
InfoWithFields logs a message at INFO level with additional structured fields.
func (*Logger) Infof ¶
Infof logs a formatted message at INFO level. Arguments are handled like fmt.Sprintf().
func (*Logger) InfofWithFields ¶
InfofWithFields logs a formatted message at INFO level with additional structured fields.
func (*Logger) IsClosed ¶
IsClosed returns true if the logger has been closed.
Example:
if !logger.IsClosed() {
logger.Info("Still logging")
}
func (*Logger) Pause ¶ added in v0.0.3
func (l *Logger) Pause()
Pause temporarily stops processing log messages. Useful for reducing logging overhead during critical sections.
Example:
logger.Pause() defer logger.Resume() // Critical section with minimal overhead
func (*Logger) RemoveOutput ¶
RemoveOutput removes a previously added output writer.
Example:
logger.RemoveOutput(os.Stdout) // Stop logging to stdout
func (*Logger) Resume ¶ added in v0.0.3
func (l *Logger) Resume()
Resume resumes processing of log messages after a Pause().
func (*Logger) SetDynamicLevelFunc ¶
SetDynamicLevelFunc sets a function that will be called for each log message to determine the current log level. This allows for runtime log level changes without requiring explicit synchronization.
Example:
logger.SetDynamicLevelFunc(func() LogLevel {
if config.DebugMode {
return DEBUG
}
return INFO
})
func (*Logger) SetLogLevel ¶
SetLogLevel changes the minimum log level that will be processed. Messages below this level will be ignored.
Example:
logger.SetLogLevel(gourdianlogger.WARN) // Only log WARN and above
func (*Logger) Warn ¶
func (l *Logger) Warn(v ...interface{})
Warn logs a message at WARN level. Arguments are handled like fmt.Sprint().
func (*Logger) WarnWithFields ¶
WarnWithFields logs a message at WARN level with additional structured fields.
func (*Logger) Warnf ¶
Warnf logs a formatted message at WARN level. Arguments are handled like fmt.Sprintf().
func (*Logger) WarnfWithFields ¶
WarnfWithFields logs a formatted message at WARN level with additional structured fields.
type LoggerConfig ¶
type LoggerConfig struct {
BackupCount int `json:"backup_count"` // Number of backup log files to keep (default: 5)
BufferSize int `json:"buffer_size"` // Size of the async buffer in messages (0 for synchronous logging, default: 0)
AsyncWorkers int `json:"async_workers"` // Number of async worker goroutines (default: 1)
MaxLogRate int `json:"max_log_rate"` // Maximum number of logs per second (0 for no limit, default: 0)
EnableCaller bool `json:"enable_caller"` // Whether to include caller information (file:line:function) (default: true)
EnableFallback bool `json:"enable_fallback"` // Whether to fallback to stderr when logging fails (default: true)
PrettyPrint bool `json:"pretty_print"` // Pretty-print JSON logs (only applies to JSON format, default: false)
MaxBytes int64 `json:"max_bytes"` // Maximum size in bytes before rotating log file (default: 10MB)
Filename string `json:"filename"` // Base filename for logs (without extension, default: "gourdianlogs")
TimestampFormat string `json:"timestamp_format"` // Timestamp format (default: "2006-01-02 15:04:05.000000")
LogsDir string `json:"logs_dir"` // Directory to store log files (default: "logs")
FormatStr string `json:"format"` // Format string ("PLAIN" or "JSON", default: "PLAIN")
LogLevel LogLevel `json:"log_level"` // Default log level (default: DEBUG)
CustomFields map[string]interface{} `json:"custom_fields"` // Custom fields to include in every log message (JSON format only)
Outputs []io.Writer `json:"-"` // Additional output writers (e.g., network connections, other files)
LogFormat LogFormat `json:"-"` // Log format (overrides FormatStr if set)
ErrorHandler func(error) `json:"-"` // Error handler function for logging errors
}
LoggerConfig contains configuration options for the logger. All fields have sensible defaults and are optional.
func (*LoggerConfig) Validate ¶
func (lc *LoggerConfig) Validate() error
Validate checks the LoggerConfig for invalid values. Returns an error if any configuration value is invalid.