Documentation
ΒΆ
Overview ΒΆ
Package log provides the world's fastest logging library for Go Zero allocations, zero compromises, pure performance
Example (GlobalLogger) ΒΆ
package main import ( "github.com/semihalev/log" ) func main() { // Global logger is ready to use immediately log.Info("Starting application") // Log with key-value pairs (v0.x compatible) log.Info("User logged in", "username", "john", "user_id", 123) // Change log level log.SetLevel(log.LevelWarn) // This won't be logged (below threshold) log.Debug("Debug message") // This will be logged log.Warn("Low memory", "available", "512MB") }
Example (Structured) ΒΆ
package main import ( "github.com/semihalev/log" ) func main() { // Create structured logger with terminal output logger := log.NewStructured() logger.SetWriter(log.StdoutTerminal()) // Log with structured fields logger.Info("User logged in", log.String("username", "john"), log.Int("user_id", 12345), log.Bool("admin", true)) logger.Error("Request failed", log.String("method", "POST"), log.String("path", "/api/users"), log.Int("status", 500), log.Float64("duration", 1.234)) // Output shows colored terminal format with fields }
Example (Terminal) ΒΆ
package main import ( "github.com/semihalev/log" ) func main() { // Create logger with beautiful terminal output logger := log.New() logger.SetWriter(log.StdoutTerminal()) // Basic logging logger.Debug("Starting application") logger.Info("Server started successfully") logger.Warn("Memory usage is high") logger.Error("Failed to connect to database") // Output shows colored terminal format }
Index ΒΆ
- Constants
- func Debug(msg string, keysAndValues ...any)
- func DebugKV(msg string, keysAndValues ...any)
- func Error(msg string, keysAndValues ...any)
- func ErrorKV(msg string, keysAndValues ...any)
- func Fatal(msg string, keysAndValues ...any)
- func FatalKV(msg string, keysAndValues ...any)
- func Info(msg string, keysAndValues ...any)
- func InfoKV(msg string, keysAndValues ...any)
- func SetDefault(logger *StructuredLogger)
- func SetLevel(level Level)
- func SetWriter(w Writer)
- func Warn(msg string, keysAndValues ...any)
- func WarnKV(msg string, keysAndValues ...any)
- type AsyncWriter
- type DiscardZeroWriter
- type Entry
- type Field
- func Any(key string, value any) Field
- func Bool(key string, val bool) Field
- func Bytes(key string, val []byte) Field
- func Float32(key string, val float32) Field
- func Float64(key string, val float64) Field
- func Int(key string, val int) Field
- func Int64(key string, val int64) Field
- func String(key string, val string) Field
- func Uint(key string, val uint) Field
- func Uint64(key string, val uint64) Field
- type FieldType
- type KV
- type Level
- type Logger
- type MMapWriter
- type NanoLogger
- type Record
- type RingBuffer
- type SimpleLogger
- func (l *SimpleLogger) Debug(v ...any)
- func (l *SimpleLogger) Debugf(format string, v ...any)
- func (l *SimpleLogger) Error(v ...any)
- func (l *SimpleLogger) Errorf(format string, v ...any)
- func (l *SimpleLogger) Fatal(v ...any)
- func (l *SimpleLogger) Fatalf(format string, v ...any)
- func (l *SimpleLogger) Info(v ...any)
- func (l *SimpleLogger) Infof(format string, v ...any)
- func (l *SimpleLogger) Warn(v ...any)
- func (l *SimpleLogger) Warnf(format string, v ...any)
- type StructuredLogger
- func (l *StructuredLogger) Debug(msg string, fields ...Field)
- func (l *StructuredLogger) DebugKV(msg string, keysAndValues ...any)
- func (l *StructuredLogger) Error(msg string, fields ...Field)
- func (l *StructuredLogger) ErrorKV(msg string, keysAndValues ...any)
- func (l *StructuredLogger) Fatal(msg string, fields ...Field)
- func (l *StructuredLogger) FatalKV(msg string, keysAndValues ...any)
- func (l *StructuredLogger) Info(msg string, fields ...Field)
- func (l *StructuredLogger) InfoKV(msg string, keysAndValues ...any)
- func (l *StructuredLogger) Warn(msg string, fields ...Field)
- func (l *StructuredLogger) WarnKV(msg string, keysAndValues ...any)
- type TerminalWriter
- type UltimateLogger
- type Writer
- type ZeroAllocLogger
- type ZeroWriter
Examples ΒΆ
Constants ΒΆ
const ( MagicHeader = 0x554C4F47 // "ULOG" Version = 1 // Cache line size for padding CacheLineSize = 64 )
Magic constants for binary format
const (
// MS_ASYNC performs asynchronous sync
MS_ASYNC = 0x1
)
Variables ΒΆ
This section is empty.
Functions ΒΆ
func SetDefault ΒΆ added in v1.1.0
func SetDefault(logger *StructuredLogger)
SetDefault sets the default global logger
Example ΒΆ
package main import ( "github.com/semihalev/log" ) func main() { // Create a custom logger logger := log.NewStructured() logger.SetWriter(log.StderrWriter) logger.SetLevel(log.LevelDebug) // Set it as the global default log.SetDefault(logger) // Now all global calls use your custom logger log.Debug("This goes to stderr") }
func SetLevel ΒΆ
func SetLevel(level Level)
SetLevel sets the minimum log level for the default logger
func SetWriter ΒΆ added in v1.1.0
func SetWriter(w Writer)
SetWriter sets the writer for the default logger
Types ΒΆ
type AsyncWriter ΒΆ added in v1.0.0
type AsyncWriter struct {
// contains filtered or unexported fields
}
AsyncWriter wraps a writer with a ring buffer for async operation
func NewAsyncWriter ΒΆ added in v1.0.0
func NewAsyncWriter(w Writer, bufferSize int) *AsyncWriter
NewAsyncWriter creates a new async writer
func (*AsyncWriter) Close ΒΆ added in v1.0.0
func (aw *AsyncWriter) Close() error
Close stops the async writer
func (*AsyncWriter) Write ΒΆ added in v1.0.0
func (aw *AsyncWriter) Write(b []byte) error
Write adds data to the ring buffer
func (*AsyncWriter) Writer ΒΆ added in v1.0.0
func (aw *AsyncWriter) Writer() Writer
Writer returns a Writer function for the logger
type DiscardZeroWriter ΒΆ added in v1.0.0
type DiscardZeroWriter struct{}
DiscardZeroWriter discards all output with zero allocations
func (DiscardZeroWriter) WriteZero ΒΆ added in v1.0.0
func (DiscardZeroWriter) WriteZero(*[256]byte, int)
type Entry ΒΆ added in v1.0.0
type Entry struct {
// contains filtered or unexported fields
}
Entry represents a log entry in the ring buffer
type Field ΒΆ added in v0.1.2
Field represents a typed field without allocations
type Logger ΒΆ
type Logger struct {
// contains filtered or unexported fields
}
Logger is the core logger - exactly one cache line (64 bytes)
type MMapWriter ΒΆ added in v1.0.0
type MMapWriter struct {
// contains filtered or unexported fields
}
MMapWriter provides zero-copy, zero-syscall logging via memory-mapped files
func NewMMapWriter ΒΆ added in v1.0.0
func NewMMapWriter(path string, size int64) (*MMapWriter, error)
NewMMapWriter creates a new memory-mapped file writer
func (*MMapWriter) Close ΒΆ added in v1.0.0
func (w *MMapWriter) Close() error
Close unmaps and closes the file
func (*MMapWriter) Write ΒΆ added in v1.0.0
func (w *MMapWriter) Write(b []byte) error
Write writes data to the memory-mapped file
func (*MMapWriter) Writer ΒΆ added in v1.0.0
func (w *MMapWriter) Writer() Writer
Writer returns a Writer function for the logger
type NanoLogger ΒΆ added in v1.0.0
type NanoLogger struct {
// contains filtered or unexported fields
}
NanoLogger - Even faster with pre-allocated message buffers
func NewNanoLogger ΒΆ added in v1.0.0
func NewNanoLogger(output func([]byte)) *NanoLogger
NewNanoLogger creates a logger that writes to a function
type Record ΒΆ
type Record struct { Sequence uint64 // 8 bytes - unique sequence Time uint64 // 8 bytes - unix nano timestamp Level Level // 1 byte MsgLen uint16 // 2 bytes - message length DataLen uint16 // 2 bytes - data length Data [32]byte // 32 bytes - inline storage for small messages // contains filtered or unexported fields }
Record represents a log entry - exactly one cache line (64 bytes)
type RingBuffer ΒΆ added in v1.0.0
type RingBuffer struct {
// contains filtered or unexported fields
}
RingBuffer is a lock-free single producer, multiple consumer ring buffer
func NewRingBuffer ΒΆ added in v1.0.0
func NewRingBuffer(size int) *RingBuffer
NewRingBuffer creates a new ring buffer with the given size (must be power of 2)
func (*RingBuffer) Get ΒΆ added in v1.0.0
func (rb *RingBuffer) Get() ([]byte, bool)
Get retrieves data from the ring buffer (multiple consumers)
func (*RingBuffer) Put ΒΆ added in v1.0.0
func (rb *RingBuffer) Put(data []byte) bool
Put adds data to the ring buffer (single producer)
type SimpleLogger ΒΆ added in v1.1.1
type SimpleLogger struct {
*Logger
}
Simple logger that accepts any values (like v0.x)
func NewSimple ΒΆ added in v1.1.1
func NewSimple() *SimpleLogger
NewSimple creates a simple logger that accepts any values
func (*SimpleLogger) Debug ΒΆ added in v1.1.1
func (l *SimpleLogger) Debug(v ...any)
Debug logs debug accepting any values
func (*SimpleLogger) Debugf ΒΆ added in v1.1.1
func (l *SimpleLogger) Debugf(format string, v ...any)
Debugf logs formatted debug
func (*SimpleLogger) Error ΒΆ added in v1.1.1
func (l *SimpleLogger) Error(v ...any)
Error logs error accepting any values
func (*SimpleLogger) Errorf ΒΆ added in v1.1.1
func (l *SimpleLogger) Errorf(format string, v ...any)
Errorf logs formatted error
func (*SimpleLogger) Fatal ΒΆ added in v1.1.1
func (l *SimpleLogger) Fatal(v ...any)
Fatal logs fatal accepting any values and exits
func (*SimpleLogger) Fatalf ΒΆ added in v1.1.1
func (l *SimpleLogger) Fatalf(format string, v ...any)
Fatalf logs formatted fatal and exits
func (*SimpleLogger) Info ΒΆ added in v1.1.1
func (l *SimpleLogger) Info(v ...any)
Info logs info accepting any values
func (*SimpleLogger) Infof ΒΆ added in v1.1.1
func (l *SimpleLogger) Infof(format string, v ...any)
Infof logs formatted info
func (*SimpleLogger) Warn ΒΆ added in v1.1.1
func (l *SimpleLogger) Warn(v ...any)
Warn logs warning accepting any values
func (*SimpleLogger) Warnf ΒΆ added in v1.1.1
func (l *SimpleLogger) Warnf(format string, v ...any)
Warnf logs formatted warning
type StructuredLogger ΒΆ added in v0.1.2
type StructuredLogger struct {
*Logger
}
StructuredLogger provides zero-allocation structured logging
func Default ΒΆ added in v1.1.0
func Default() *StructuredLogger
Default returns the current default logger
func NewStructured ΒΆ added in v0.1.2
func NewStructured() *StructuredLogger
NewStructured creates a new structured logger
func (*StructuredLogger) Debug ΒΆ added in v0.1.2
func (l *StructuredLogger) Debug(msg string, fields ...Field)
Debug logs a debug message with fields
func (*StructuredLogger) DebugKV ΒΆ added in v1.1.1
func (l *StructuredLogger) DebugKV(msg string, keysAndValues ...any)
DebugKV logs debug with key-value pairs (backward compatible)
func (*StructuredLogger) Error ΒΆ added in v0.1.2
func (l *StructuredLogger) Error(msg string, fields ...Field)
Error logs an error message with fields
func (*StructuredLogger) ErrorKV ΒΆ added in v1.1.1
func (l *StructuredLogger) ErrorKV(msg string, keysAndValues ...any)
ErrorKV logs error with key-value pairs (backward compatible)
func (*StructuredLogger) Fatal ΒΆ added in v1.0.0
func (l *StructuredLogger) Fatal(msg string, fields ...Field)
Fatal logs a fatal message with fields and exits
func (*StructuredLogger) FatalKV ΒΆ added in v1.1.1
func (l *StructuredLogger) FatalKV(msg string, keysAndValues ...any)
FatalKV logs fatal with key-value pairs and exits (backward compatible)
func (*StructuredLogger) Info ΒΆ added in v0.1.2
func (l *StructuredLogger) Info(msg string, fields ...Field)
Info logs an info message with fields
func (*StructuredLogger) InfoKV ΒΆ added in v1.1.1
func (l *StructuredLogger) InfoKV(msg string, keysAndValues ...any)
InfoKV logs info with key-value pairs (backward compatible)
func (*StructuredLogger) Warn ΒΆ added in v0.1.2
func (l *StructuredLogger) Warn(msg string, fields ...Field)
Warn logs a warning message with fields
func (*StructuredLogger) WarnKV ΒΆ added in v1.1.1
func (l *StructuredLogger) WarnKV(msg string, keysAndValues ...any)
WarnKV logs warning with key-value pairs (backward compatible)
type TerminalWriter ΒΆ added in v1.0.0
type TerminalWriter struct {
// contains filtered or unexported fields
}
TerminalWriter decodes binary log format and outputs beautiful terminal format
func NewTerminalWriter ΒΆ added in v1.0.0
func NewTerminalWriter(out *os.File) *TerminalWriter
NewTerminalWriter creates a new terminal writer
func (*TerminalWriter) Write ΒΆ added in v1.0.0
func (w *TerminalWriter) Write(b []byte) error
Write decodes binary log and outputs formatted text
func (*TerminalWriter) Writer ΒΆ added in v1.0.0
func (w *TerminalWriter) Writer() Writer
Writer returns a Writer function for the logger
type UltimateLogger ΒΆ added in v1.0.0
type UltimateLogger struct {
// contains filtered or unexported fields
}
UltimateLogger - The world's fastest logger with ZERO allocations Uses direct memory writes and inlined operations
func NewUltimateLogger ΒΆ added in v1.0.0
func NewUltimateLogger() *UltimateLogger
NewUltimateLogger creates the ultimate zero-allocation logger
func (*UltimateLogger) Debug ΒΆ added in v1.0.0
func (l *UltimateLogger) Debug(msg string)
Debug logs a debug message
func (*UltimateLogger) Error ΒΆ added in v1.0.0
func (l *UltimateLogger) Error(msg string)
Error logs an error message
func (*UltimateLogger) GetBuffer ΒΆ added in v1.0.0
func (l *UltimateLogger) GetBuffer() ([]byte, uint64)
GetBuffer returns the current position in the buffer for reading
func (*UltimateLogger) Info ΒΆ added in v1.0.0
func (l *UltimateLogger) Info(msg string)
Info logs with absolutely zero allocations
func (*UltimateLogger) SetLevel ΒΆ added in v1.0.0
func (l *UltimateLogger) SetLevel(level Level)
SetLevel sets the log level
type Writer ΒΆ added in v1.0.0
Writer is a function that writes log data
StderrWriter writes to stderr
StdoutWriter writes to stdout
func StderrTerminal ΒΆ added in v1.0.0
func StderrTerminal() Writer
StderrTerminal creates a terminal writer for stderr
func StdoutTerminal ΒΆ added in v1.0.0
func StdoutTerminal() Writer
StdoutTerminal creates a terminal writer for stdout
type ZeroAllocLogger ΒΆ added in v0.1.2
type ZeroAllocLogger struct {
// contains filtered or unexported fields
}
ZeroAllocLogger is the world's fastest logger - truly zero allocations
func NewZeroAllocLogger ΒΆ added in v0.1.2
func NewZeroAllocLogger() *ZeroAllocLogger
NewZeroAllocLogger creates the fastest possible logger
func (*ZeroAllocLogger) Debug ΒΆ added in v0.1.2
func (l *ZeroAllocLogger) Debug(msg string)
Debug logs a debug message
func (*ZeroAllocLogger) Error ΒΆ added in v0.1.2
func (l *ZeroAllocLogger) Error(msg string)
Error logs an error message
func (*ZeroAllocLogger) Info ΒΆ added in v0.1.2
func (l *ZeroAllocLogger) Info(msg string)
Info logs an info message with zero allocations
func (*ZeroAllocLogger) SetLevel ΒΆ added in v0.1.2
func (l *ZeroAllocLogger) SetLevel(level Level)
SetLevel atomically sets the log level
func (*ZeroAllocLogger) SetZeroWriter ΒΆ added in v1.0.0
func (l *ZeroAllocLogger) SetZeroWriter(w ZeroWriter)
SetZeroWriter atomically sets the writer
func (*ZeroAllocLogger) Warn ΒΆ added in v0.1.2
func (l *ZeroAllocLogger) Warn(msg string)
Warn logs a warning message
type ZeroWriter ΒΆ added in v1.0.0
type ZeroWriter interface { // WriteZero writes with zero allocations - buffer is reused WriteZero(buf *[256]byte, n int) }
ZeroWriter is a zero-allocation writer interface