turbolog

🎯 Why TurboLog?

TurboLog is a production-ready logging library that combines blazing-fast performance with enterprise security features. Perfect for high-throughput microservices requiring zero-latency logging with automatic sensitive data protection.

Performance at a Glance

TurboLog Basic:      202.6 ns/op    0 B/op    0 allocs/op  ⚡
TurboLog WithFields: 381.1 ns/op    0 B/op    0 allocs/op
TurboLog Disabled:     2.1 ns/op    0 B/op    0 allocs/op  🚀 Fastest!
TurboLog Concurrent:  39.9 ns/op    0 B/op    0 allocs/op

vs Zerolog:           71.1 ns/op    0 B/op    0 allocs/op  (raw baseline)
vs Zap:              401.5 ns/op    0 B/op    0 allocs/op  (2x slower)
vs Logrus:          1191  ns/op  412 B/op   13 allocs/op  (6x slower)

TurboLog is 2x faster than Zap and 6x faster than Logrus while maintaining full CloudWeGo Hertz compatibility and enterprise features.

✨ Features

Security Features

Auto-scrubs sensitive data:

• 🔐 Passwords, secrets, passphrases
• 🔑 API keys, access tokens, bearer tokens
• 🎫 JWT tokens, session IDs
• ☁️ AWS credentials (AKIA*, SECRET_KEY)
• 💳 Credit card numbers
• 📧 Email addresses (partial masking)
• 🗄️ Database connection strings

📦 Installation

go get github.com/a-issaoui/turbolog

Requirements: Go 1.24.0+

🚀 Quick Start

Basic Usage

package main

import (
    "context"
    "time"
    "github.com/a-issaoui/turbolog"
)

func main() {
    log := turbolog.Init()
    defer log.Shutdown()

    // Simple logging
    log.Info("Application started")
    log.Warn("This is a warning")
    log.Error("This is an error")

    // Structured logging with key-value pairs (NEW in v1.0.9!)
    log.Info("HTTP request", "method", "GET", "path", "/api/users", "status", 200)

    // Context-aware structured logging (NEW in v1.0.9!)
    ctx := context.Background()
    turbolog.CtxInfo(ctx, "Database query", "table", "users", "duration_ms", 45)

    // Structured logging with Event API
    log.InfoEvent().
        Str("user_id", "user-123").
        Int("count", 42).
        Dur("latency", 15*time.Millisecond).
        Msg("Request processed")

    // Formatted logging
    log.Infof("Processing item %d of %d", 5, 10)
}

Hertz Framework Integration

import (
    "github.com/a-issaoui/turbolog"
    "github.com/cloudwego/hertz/pkg/common/hlog"
)

func main() {
    // Set TurboLog as Hertz logger
    turbolog.SetHertzLogger()

    // Structured logging with key-value pairs (v1.0.9+)
    hlog.Info("HTTP request", "method", "GET", "status", 200, "path", "/api/users")

    // Context-aware logging
    hlog.CtxInfof(ctx, "Request processed: %s", path)

    // Traditional formatted logging
    hlog.Info("Server started")
}

Production Configuration

config := turbolog.NewConfig()

// Core settings
config.Level = turbolog.LevelInfo
config.Format = "json"
config.Environment = "production"

// Performance
config.UseDialode = true
config.DiodeBufferSize = 5000

// Security
config.ScrubSensitiveData = true

// File rotation
config.FileEnabled = true
config.FilePath = "/var/log/app/app.log"
config.FileMaxSize = 100    // MB
config.FileMaxAge = 30      // days
config.FileCompress = true

log := turbolog.InitWithConfig(config)
defer log.Shutdown()

⚡ Performance

Benchmark Results

System: Linux 6.12.0, Intel Core i7-10750H @ 2.60GHz, Go 1.25.3

Benchmark                         | Time        | Memory    | Allocations
----------------------------------|-------------|-----------|-------------
BenchmarkTurbologBasic            | 202.6 ns/op | 0 B/op    | 0 allocs/op
BenchmarkTurbologWithFields       | 381.1 ns/op | 0 B/op    | 0 allocs/op
BenchmarkStructuredLogging (NEW)  | 395.2 ns/op | 0 B/op    | 0 allocs/op
BenchmarkCtxStructuredLogging     | 388.5 ns/op | 0 B/op    | 0 allocs/op
BenchmarkTurbologDisabled         |   2.1 ns/op | 0 B/op    | 0 allocs/op
BenchmarkTurbologConcurrent       |  39.9 ns/op | 0 B/op    | 0 allocs/op

BenchmarkZerologBasic             |  71.1 ns/op | 0 B/op    | 0 allocs/op
BenchmarkZerologWithFields        | 255.0 ns/op | 0 B/op    | 0 allocs/op
BenchmarkZerologConcurrent        |  30.6 ns/op | 0 B/op    | 0 allocs/op

BenchmarkZapBasic                 | 401.5 ns/op | 0 B/op    | 0 allocs/op
BenchmarkZapWithFields            | 760.0 ns/op | 256 B/op  | 1 allocs/op

BenchmarkLogrusBasic              |  1191 ns/op | 412 B/op  | 13 allocs/op
BenchmarkLogrusWithFields         |  3044 ns/op | 1285 B/op | 20 allocs/op

Key Achievements:

• ✅ Zero allocations maintained
• ✅ 2x faster than Zap
• ✅ 6x faster than Logrus
• ✅ Fastest disabled check (2.1ns)
• ✅ Excellent concurrent performance (39.9ns)

Why Not Match Zerolog's 71ns?

TurboLog adds 130ns overhead for CloudWeGo Hertz hlog compatibility:

• ~70ns: Interface conversion (formatArgs)
• ~20ns: Wrapper function calls
• ~10ns: Metric recording
• ~30ns: Other compatibility overhead

This is architectural - the cost of 100% hlog compatibility. You cannot eliminate it without breaking the API.

📚 Documentation

Log Levels

turbolog.LevelTrace   // Detailed debugging
turbolog.LevelDebug   // Debugging information
turbolog.LevelInfo    // General information (default)
turbolog.LevelNotice  // Normal but significant
turbolog.LevelWarn    // Warning messages
turbolog.LevelError   // Error messages
turbolog.LevelFatal   // Fatal errors (exits program)

Logging Methods

Simple:

log.Info("message")
log.Warn("warning")
log.Error("error")

Formatted:

log.Infof("Processing %d items", count)
log.Errorf("Failed: %v", err)

Structured (Zero Allocations):

log.InfoEvent().
    Str("user_id", "123").
    Int("count", 42).
    Dur("latency", 15*time.Millisecond).
    Msg("Request processed")

Context-Aware:

log.CtxInfof(ctx, "Processing user %s", userID)

Specialized Logging

// HTTP request logging
log.LogHTTPRequest("GET", "/api/users", 200, 45*time.Millisecond, "192.168.1.1")

// Database query logging
log.LogDatabaseQuery("SELECT * FROM users", 12*time.Millisecond, nil)

// Cache operation logging
log.LogCacheOperation("get", "user:456", true, 2*time.Millisecond)

🔐 Sensitive Data Scrubbing

config := turbolog.NewConfig()
config.ScrubSensitiveData = true
log := turbolog.InitWithConfig(config)

// Input
log.Info("User login: password=secret123, token=eyJhbGc...")

// Output (automatically scrubbed)
// {"level":"info","message":"User login: password=[REDACTED], token=[JWT_REDACTED]"}

What Gets Scrubbed:

• Passwords, API keys, bearer tokens
• JWT tokens, session IDs
• AWS credentials (AKIA*, SECRET_KEY)
• Credit card numbers
• Email addresses (partial: us**@example.com)
• Database connection strings

📊 Metrics Integration

type PrometheusRecorder struct {
    logsTotal *prometheus.CounterVec
}

func (p *PrometheusRecorder) IncLog(level turbolog.Level) {
    p.logsTotal.WithLabelValues(level.String()).Inc()
}

// Configure logger with metrics
config := turbolog.NewConfig()
config.MetricsRecorder = NewPrometheusRecorder()
log := turbolog.InitWithConfig(config)

Full example: examples/metrics/prometheus_example.go

🧪 Testing

# Run all tests
go test -v ./...

# Run with race detector
go test -race ./...

# Run benchmarks
go test -bench=. -benchmem ./...

Test Coverage:

• ✅ Zero race conditions (verified with -race)
• ✅ Concurrent stress tests
• ✅ Hertz hlog compatibility tests
• ✅ Production simulation tests

🏗️ Architecture

Application Code
       ↓
TurboLog Logger (hlog compatible)
       ↓
Zerolog Core (zero-allocation)
       ↓
Optional: Scrubber / Diode / Batching
       ↓
Output: Console / File / Centralized

💡 Examples

• Basic: examples/basic/main.go
• Advanced: examples/advanced/main.go (production features)
• HTTP Server: examples/production/main.go
• Hertz Integration: examples/hlog/main.go
• Metrics: examples/metrics/prometheus_example.go

cd examples/basic && go run main.go

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built on:

• zerolog - Zero-allocation JSON logger
• lumberjack - Log rotation
• diode - Non-blocking I/O

Special thanks to CloudWeGo for Hertz.

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions