gookit/slog Documentation

The handler package provides several pre-configured slog.Handler implementations for different output destinations and behaviors:

• Console: For logging to the terminal/console.
• File: For logging to local files.
• Stream: For logging to an io.Writer.
• Syslog: For logging to the system log.
• Email: For sending logs via email.
• FlushClose: A wrapper that ensures logs are flushed and the underlying writer is closed.
• SyncClose: A handler designed for file-based logging that ensures synchronization and closing of files.

Performance Limitation: Lack of Logger-level Level Gates

Currently, the library lacks a "fast gate" at the Logger level for checking log levels.

The Issue: Even if a log level is disabled (e.g., Debug is disabled in production), the library performs message formatting (e.g., fmt.Sprintf or calling Stringer.String()) before checking if the level is enabled. This means disabled logs still incur the CPU and allocation costs of argument formatting and lock contention.

Affected Files:

• record.go (lines 348-371)
• logger_write.go (lines 60-95)

Impact: High-frequency disabled logs (like Debug) will still consume significant resources in production environments.

Performance Limitation: Single Mutex Bottleneck

In the current implementation, the entire process of formatting a log and writing it to the output occurs while holding a single mutex (l.mu) on the logger.

The Issue: writeRecord holds the lock during:

1. Caller stack trace retrieval
2. Processor execution
3. Formatting (CPU intensive)
4. I/O operations

Impact: Under high concurrency, throughput is limited by this single lock, as formatting (which could be done in parallel per record) is forced to be serial.

Many handler constructors (especially those in SyncCloseHandler) accept variadic ConfigFn arguments. These functions allow you to customize the handler's behavior using a builder-like pattern.

Common configuration options include:

• File/Rotation: WithLogfile, WithMaxSize, WithRotateMode, WithRotateTime, WithBackupNum, WithCompress.
• Buffering: WithBuffMode, WithBuffSize.
• Levels: WithLogLevel, WithLogLevels, WithLevelNames, WithMaxLevelName.
• Format: WithUseJSON (to switch between text and JSON output).
• Permissions: WithFilePerm.

// Example of using ConfigFn with a file handler
handler.NewFileHandler("app.log", 
    handler.WithUseJSON(true),
    handler.WithMaxSize(1024 * 1024 * 10), // 10MB
    handler.WithCompress(true),
)

Choose gookit/slog when you need a 'batteries-included' logger for applications or CLI tools. It provides features that the standard library lacks, such as:

• Built-in file rotation (size/time based, cleanup, and gzip).
• Colored and template-based console output.
• Multiple built-in handlers (file, syslog, email, buffered, multi).
• Support for Fatal and Panic levels.

Choose the standard log/slog when you want a zero-dependency, high-performance logger for libraries or services where you intend to provide your own sinks.

When using file handlers, you can configure how logs are buffered using BuffMode. This is controlled via the Config.BuffMode field or configuration functions.

• BuffModeBite (Byte buffering): The buffer writes to the file once it reaches the specified BuffSize in bytes.
• BuffModeLine (Line buffering): The buffer ensures that logs are written only when a complete line is formed, preventing log content from being truncated mid-line.

Important: If write buffering is enabled, you must call slog.MustClose() or logger.Close() at the end of your program to flush the remaining contents of the buffer to the file.

Since rotatefile.Writer implements the io.Writer interface, you can use it with the standard Go log/slog package (Go 1.21+) to get advanced file rotation features while maintaining the standard API.

package main

import (
	"log/slog"
	"github.com/gookit/rotatefile"
)

func main() {
	// Configure rotation via rotatefile.NewConfig
	w, err := rotatefile.NewConfig("testdata/std_slog.log", func(c *rotatefile.Config) {
		c.MaxSize = 50 * 1024 * 1024 // 50MB
		c.RotateTime = rotatefile.EveryDay
		c.BackupNum = 7
	}).Create()
	if err != nil {
		panic(err)
	}

	// Plug the rotatefile writer into a standard slog handler
	logger := slog.New(slog.NewJSONHandler(w, nil))
	logger.Info("log message via std log/slog", "key", "value")
}

Alternatively, you can run the benchmarks directly using the go test command. This allows for more granular control over CPU usage, verbosity, and benchmark duration.

go test -v -cpu=4 -run=none -bench=. -benchtime=10s -benchmem bench_loglibs_test.go