lixen/log
SHA256
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

e1.4.4 Fix module path and dependency issues, compatibility package added.

Browse Source
This commit is contained in:
Lixen Wraith
2025-07-08 22:13:11 -04:00
parent 7ce7158841
commit ccbe65bf40
22 changed files with 776 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
compat/README.md Normal file
View File

@ -0,0 +1,188 @@
# Compatibility Adapters for lixenwraith/log
This package provides compatibility adapters to use the `github.com/lixenwraith/log` logger with popular Go networking frameworks:
- **gnet v2**: High-performance event-driven networking framework
- **fasthttp**: Fast HTTP implementation
## Features
- ✅ Full interface compatibility with both frameworks
- ✅ Preserves structured logging capabilities
- ✅ Configurable fatal behavior for gnet
- ✅ Automatic log level detection for fasthttp
- ✅ Optional structured field extraction from printf formats
- ✅ Thread-safe and high-performance
- ✅ Shared logger instance for multiple adapters
## Installation
```bash
go get github.com/lixenwraith/log
```
## Quick Start
### Basic Usage with gnet
```go
import (
"github.com/lixenwraith/log"
"github.com/lixenwraith/log/compat"
"github.com/panjf2000/gnet/v2"
)
// Create and configure logger
logger := log.NewLogger()
logger.InitWithDefaults("directory=/var/log/gnet", "level=-4")
defer logger.Shutdown()
// Create gnet adapter
adapter := compat.NewGnetAdapter(logger)
// Use with gnet
gnet.Run(eventHandler, "tcp://127.0.0.1:9000", gnet.WithLogger(adapter))
```
### Basic Usage with fasthttp
```go
import (
"github.com/lixenwraith/log"
"github.com/lixenwraith/log/compat"
"github.com/valyala/fasthttp"
)
// Create and configure logger
logger := log.NewLogger()
logger.InitWithDefaults("directory=/var/log/fasthttp")
defer logger.Shutdown()
// Create fasthttp adapter
adapter := compat.NewFastHTTPAdapter(logger)
// Use with fasthttp
server := &fasthttp.Server{
Handler: requestHandler,
Logger: adapter,
}
server.ListenAndServe(":8080")
```
### Using the Builder Pattern
```go
// Create adapters with shared configuration
builder := compat.NewBuilder().
WithOptions(
"directory=/var/log/app",
"level=0",
"format=json",
"max_size_mb=100",
)
gnetAdapter, fasthttpAdapter, err := builder.Build()
if err != nil {
panic(err)
}
defer builder.GetLogger().Shutdown()
```
## Advanced Features
### Structured Field Extraction
The structured adapters can extract key-value pairs from printf-style format strings:
```go
// Use structured adapter
adapter := compat.NewStructuredGnetAdapter(logger)
// These calls will extract structured fields:
adapter.Infof("client=%s port=%d", "192.168.1.1", 8080)
// Logs: {"client": "192.168.1.1", "port": 8080, "source": "gnet"}
adapter.Errorf("user: %s, action: %s, error: %s", "john", "login", "invalid password")
// Logs: {"user": "john", "action": "login", "error": "invalid password", "source": "gnet"}
```
### Custom Fatal Handling
```go
adapter := compat.NewGnetAdapter(logger,
compat.WithFatalHandler(func(msg string) {
// Custom cleanup
saveState()
notifyAdmin(msg)
os.Exit(1)
}),
)
```
### Custom Level Detection for fasthttp
```go
adapter := compat.NewFastHTTPAdapter(logger,
compat.WithDefaultLevel(log.LevelInfo),
compat.WithLevelDetector(func(msg string) int64 {
if strings.Contains(msg, "CRITICAL") {
return log.LevelError
}
return 0 // Use default detection
}),
)
```
## Configuration Examples
### High-Performance Configuration
```go
builder := compat.NewBuilder().
WithOptions(
"directory=/var/log/highperf",
"level=0", // Info and above
"format=json", // Structured logs
"buffer_size=4096", // Large buffer
"flush_interval_ms=1000", // Less frequent flushes
"enable_periodic_sync=false", // Disable periodic sync
)
```
### Development Configuration
```go
builder := compat.NewBuilder().
WithOptions(
"directory=./logs",
"level=-4", // Debug level
"format=txt", // Human-readable
"show_timestamp=true",
"show_level=true",
"trace_depth=3", // Include call traces
"flush_interval_ms=100", // Frequent flushes
)
```
### Production Configuration with Monitoring
```go
builder := compat.NewBuilder().
WithOptions(
"directory=/var/log/prod",
"level=0",
"format=json",
"max_size_mb=1000", // 1GB files
"max_total_size_mb=10000", // 10GB total
"retention_period_hrs=168", // 7 days
"heartbeat_level=2", // Process + disk heartbeats
"heartbeat_interval_s=300", // 5 minutes
)
```
## Performance Considerations
1. **Printf Overhead**: The adapters must format printf-style strings, adding minimal overhead
2. **Structured Extraction**: The structured adapters use regex matching, which adds ~1-2μs per call
3. **Level Detection**: FastHTTP adapter's level detection adds <100ns for simple string checks
4. **Buffering**: The underlying logger's buffering minimizes I/O impact

72
compat/builder.go Normal file
View File

@ -0,0 +1,72 @@
// FILE: compat/builder.go
package compat
import (
"github.com/lixenwraith/log"
"github.com/panjf2000/gnet/v2"
"github.com/valyala/fasthttp"
)
// Builder provides a convenient way to create configured loggers for both frameworks
type Builder struct {
logger *log.Logger
options []string // InitWithDefaults options
}
// NewBuilder creates a new adapter builder
func NewBuilder() *Builder {
return &Builder{
logger: log.NewLogger(),
}
}
// WithOptions adds configuration options for the underlying logger
func (b *Builder) WithOptions(opts ...string) *Builder {
b.options = append(b.options, opts...)
return b
}
// Build initializes the logger and returns adapters for both frameworks
func (b *Builder) Build() (*GnetAdapter, *FastHTTPAdapter, error) {
// Initialize the logger
if err := b.logger.InitWithDefaults(b.options...); err != nil {
return nil, nil, err
}
// Create adapters
gnetAdapter := NewGnetAdapter(b.logger)
fasthttpAdapter := NewFastHTTPAdapter(b.logger)
return gnetAdapter, fasthttpAdapter, nil
}
// BuildStructured initializes the logger and returns structured adapters
func (b *Builder) BuildStructured() (*StructuredGnetAdapter, *FastHTTPAdapter, error) {
// Initialize the logger
if err := b.logger.InitWithDefaults(b.options...); err != nil {
return nil, nil, err
}
// Create adapters
gnetAdapter := NewStructuredGnetAdapter(b.logger)
fasthttpAdapter := NewFastHTTPAdapter(b.logger)
return gnetAdapter, fasthttpAdapter, nil
}
// GetLogger returns the underlying logger for direct access
func (b *Builder) GetLogger() *log.Logger {
return b.logger
}
// Example usage functions
// ConfigureGnetServer configures a gnet server with the logger
func ConfigureGnetServer(adapter *GnetAdapter, opts ...gnet.Option) []gnet.Option {
return append(opts, gnet.WithLogger(adapter))
}
// ConfigureFastHTTPServer configures a fasthttp server with the logger
func ConfigureFastHTTPServer(adapter *FastHTTPAdapter, server *fasthttp.Server) {
server.Logger = adapter
}

103
compat/fasthttp.go Normal file
View File

@ -0,0 +1,103 @@
// FILE: compat/fasthttp.go
package compat
import (
"fmt"
"strings"
"github.com/lixenwraith/log"
)
// FastHTTPAdapter wraps lixenwraith/log.Logger to implement fasthttp's Logger interface
type FastHTTPAdapter struct {
logger *log.Logger
defaultLevel int64
levelDetector func(string) int64 // Function to detect log level from message
}
// NewFastHTTPAdapter creates a new fasthttp-compatible logger adapter
func NewFastHTTPAdapter(logger *log.Logger, opts ...FastHTTPOption) *FastHTTPAdapter {
adapter := &FastHTTPAdapter{
logger: logger,
defaultLevel: log.LevelInfo,
levelDetector: DetectLogLevel, // Default level detection
}
for _, opt := range opts {
opt(adapter)
}
return adapter
}
// FastHTTPOption allows customizing adapter behavior
type FastHTTPOption func(*FastHTTPAdapter)
// WithDefaultLevel sets the default log level for Printf calls
func WithDefaultLevel(level int64) FastHTTPOption {
return func(a *FastHTTPAdapter) {
a.defaultLevel = level
}
}
// WithLevelDetector sets a custom function to detect log level from message content
func WithLevelDetector(detector func(string) int64) FastHTTPOption {
return func(a *FastHTTPAdapter) {
a.levelDetector = detector
}
}
// Printf implements fasthttp's Logger interface
func (a *FastHTTPAdapter) Printf(format string, args ...interface{}) {
msg := fmt.Sprintf(format, args...)
// Detect log level from message content
level := a.defaultLevel
if a.levelDetector != nil {
detected := a.levelDetector(msg)
if detected != 0 {
level = detected
}
}
// Log with appropriate level
switch level {
case log.LevelDebug:
a.logger.Debug("msg", msg, "source", "fasthttp")
case log.LevelWarn:
a.logger.Warn("msg", msg, "source", "fasthttp")
case log.LevelError:
a.logger.Error("msg", msg, "source", "fasthttp")
default:
a.logger.Info("msg", msg, "source", "fasthttp")
}
}
// DetectLogLevel attempts to detect log level from message content
func DetectLogLevel(msg string) int64 {
msgLower := strings.ToLower(msg)
// Check for error indicators
if strings.Contains(msgLower, "error") ||
strings.Contains(msgLower, "failed") ||
strings.Contains(msgLower, "fatal") ||
strings.Contains(msgLower, "panic") {
return log.LevelError
}
// Check for warning indicators
if strings.Contains(msgLower, "warn") ||
strings.Contains(msgLower, "warning") ||
strings.Contains(msgLower, "deprecated") {
return log.LevelWarn
}
// Check for debug indicators
if strings.Contains(msgLower, "debug") ||
strings.Contains(msgLower, "trace") {
return log.LevelDebug
}
// Default to info level
return log.LevelInfo
}

79
compat/gnet.go Normal file
View File

@ -0,0 +1,79 @@
// FILE: compat/gnet.go
package compat
import (
"fmt"
"os"
"time"
"github.com/lixenwraith/log"
)
// GnetAdapter wraps lixenwraith/log.Logger to implement gnet's logging.Logger interface
type GnetAdapter struct {
logger *log.Logger
fatalHandler func(msg string) // Customizable fatal behavior
}
// NewGnetAdapter creates a new gnet-compatible logger adapter
func NewGnetAdapter(logger *log.Logger, opts ...GnetOption) *GnetAdapter {
adapter := &GnetAdapter{
logger: logger,
fatalHandler: func(msg string) {
os.Exit(1) // Default behavior matches gnet expectations
},
}
for _, opt := range opts {
opt(adapter)
}
return adapter
}
// GnetOption allows customizing adapter behavior
type GnetOption func(*GnetAdapter)
// WithFatalHandler sets a custom fatal handler
func WithFatalHandler(handler func(string)) GnetOption {
return func(a *GnetAdapter) {
a.fatalHandler = handler
}
}
// Debugf logs at debug level with printf-style formatting
func (a *GnetAdapter) Debugf(format string, args ...interface{}) {
msg := fmt.Sprintf(format, args...)
a.logger.Debug("msg", msg, "source", "gnet")
}
// Infof logs at info level with printf-style formatting
func (a *GnetAdapter) Infof(format string, args ...interface{}) {
msg := fmt.Sprintf(format, args...)
a.logger.Info("msg", msg, "source", "gnet")
}
// Warnf logs at warn level with printf-style formatting
func (a *GnetAdapter) Warnf(format string, args ...interface{}) {
msg := fmt.Sprintf(format, args...)
a.logger.Warn("msg", msg, "source", "gnet")
}
// Errorf logs at error level with printf-style formatting
func (a *GnetAdapter) Errorf(format string, args ...interface{}) {
msg := fmt.Sprintf(format, args...)
a.logger.Error("msg", msg, "source", "gnet")
}
// Fatalf logs at error level and triggers fatal handler
func (a *GnetAdapter) Fatalf(format string, args ...interface{}) {
msg := fmt.Sprintf(format, args...)
a.logger.Error("msg", msg, "source", "gnet", "fatal", true)
// Ensure log is flushed before exit
_ = a.logger.Flush(100 * time.Millisecond)
if a.fatalHandler != nil {
a.fatalHandler(msg)
}
}

131
compat/structured.go Normal file
View File

@ -0,0 +1,131 @@
// FILE: compat/structured.go
package compat
import (
"fmt"
"regexp"
"strings"
"github.com/lixenwraith/log"
)
// parseFormat attempts to extract structured fields from printf-style format strings
// This is useful for preserving structured logging semantics
func parseFormat(format string, args []interface{}) []interface{} {
// Pattern to detect common structured patterns like "key=%v" or "key: %v"
keyValuePattern := regexp.MustCompile(`(\w+)\s*[:=]\s*%[vsdqxXeEfFgGpbcU]`)
matches := keyValuePattern.FindAllStringSubmatchIndex(format, -1)
if len(matches) == 0 || len(matches) > len(args) {
// Fallback to simple message if pattern doesn't match
return []interface{}{"msg", fmt.Sprintf(format, args...)}
}
// Build structured fields
fields := make([]interface{}, 0, len(matches)*2+2)
lastEnd := 0
argIndex := 0
for _, match := range matches {
// Add any text before this match as part of the message
if match[0] > lastEnd {
prefix := format[lastEnd:match[0]]
if strings.TrimSpace(prefix) != "" {
if len(fields) == 0 {
fields = append(fields, "msg", strings.TrimSpace(prefix))
}
}
}
// Extract key name
keyStart := match[2]
keyEnd := match[3]
key := format[keyStart:keyEnd]
// Get corresponding value
if argIndex < len(args) {
fields = append(fields, key, args[argIndex])
argIndex++
}
lastEnd = match[1]
}
// Handle remaining format string and args
if lastEnd < len(format) {
remainingFormat := format[lastEnd:]
remainingArgs := args[argIndex:]
if len(remainingArgs) > 0 {
remaining := fmt.Sprintf(remainingFormat, remainingArgs...)
if strings.TrimSpace(remaining) != "" {
if len(fields) == 0 {
fields = append(fields, "msg", strings.TrimSpace(remaining))
} else {
// Append to existing message
for i := 0; i < len(fields); i += 2 {
if fields[i] == "msg" {
fields[i+1] = fmt.Sprintf("%v %s", fields[i+1], strings.TrimSpace(remaining))
break
}
}
}
}
}
}
return fields
}
// StructuredGnetAdapter provides enhanced structured logging for gnet
type StructuredGnetAdapter struct {
*GnetAdapter
extractFields bool
}
// NewStructuredGnetAdapter creates a gnet adapter with structured field extraction
func NewStructuredGnetAdapter(logger *log.Logger, opts ...GnetOption) *StructuredGnetAdapter {
return &StructuredGnetAdapter{
GnetAdapter: NewGnetAdapter(logger, opts...),
extractFields: true,
}
}
// Debugf logs with structured field extraction
func (a *StructuredGnetAdapter) Debugf(format string, args ...interface{}) {
if a.extractFields {
fields := parseFormat(format, args)
a.logger.Debug(append(fields, "source", "gnet")...)
} else {
a.GnetAdapter.Debugf(format, args...)
}
}
// Infof logs with structured field extraction
func (a *StructuredGnetAdapter) Infof(format string, args ...interface{}) {
if a.extractFields {
fields := parseFormat(format, args)
a.logger.Info(append(fields, "source", "gnet")...)
} else {
a.GnetAdapter.Infof(format, args...)
}
}
// Warnf logs with structured field extraction
func (a *StructuredGnetAdapter) Warnf(format string, args ...interface{}) {
if a.extractFields {
fields := parseFormat(format, args)
a.logger.Warn(append(fields, "source", "gnet")...)
} else {
a.GnetAdapter.Warnf(format, args...)
}
}
// Errorf logs with structured field extraction
func (a *StructuredGnetAdapter) Errorf(format string, args ...interface{}) {
if a.extractFields {
fields := parseFormat(format, args)
a.logger.Error(append(fields, "source", "gnet")...)
} else {
a.GnetAdapter.Errorf(format, args...)
}
}