Add logger package with performance benchmarks

logger/readme.md

@@ -0,0 +1,129 @@
+# Logger
+
+A lightweight, structured logging package for Go.
+
+## Features
+
+- **Simple API**: Format strings and structured fields
+- **Global & Instance**: Use default global logger or create custom instances
+- **Context Support**: Extract trace_id from context automatically
+- **Multiple Formats**: Text (default) and JSON
+- **Level Filtering**: DEBUG, INFO, WARN, ERROR, FATAL, PANIC
+- **No Dependencies**: Standard library only
+
+## Quick Start
+
+```go
+import "gitea.loveuer.com/loveuer/upkg/logger"
+
+// Global logger (default)
+logger.Info("hello %s", "world")
+logger.Error("failed: %v", err)
+
+// With fields
+logger.InfoField("user logged in",
+    "user_id", 123,
+    "action", "login",
+)
+
+// Context with trace_id
+ctx := context.WithValue(ctx, "trace_id", "req-123")
+logger.InfoCtx(ctx, "request processed")
+```
+
+## Custom Logger
+
+```go
+log := logger.New(
+    logger.WithLevel(logger.DEBUG),
+    logger.WithFormat(logger.JSON),
+    logger.WithOutput(logger.Stdout),
+    logger.WithCaller(true),
+)
+
+log.Info("custom logger")
+log.InfoField("event", "key", "value")
+```
+
+## API
+
+### Level Methods
+
+```go
+log.Debug(format string, args ...)
+log.Info(format string, args ...)
+log.Warn(format string, args ...)
+log.Error(format string, args ...)
+log.Fatal(format string, args ...)
+log.Panic(format string, args ...)
+```
+
+### Context Methods
+
+```go
+log.InfoCtx(ctx, format string, args ...)
+// Automatically adds trace_id from ctx as a field
+```
+
+### Field Methods
+
+```go
+log.InfoField(message string, keyValues ...interface{})
+// Example: log.InfoField("user created", "id", 123, "name", "john")
+```
+
+## Configuration Options
+
+```go
+logger.New(
+    WithLevel(INFO),              // Minimum log level
+    WithFormat(TEXT),             // TEXT or JSON
+    WithOutput(Stdout),           // Stdout, Stderr, or use WithOutputFile
+    WithOutputFile("/path/to.log"), // Write to file
+    WithCaller(true),             // Include file:line in output
+    WithFieldKey("trace_id"),     // Context field key name
+    WithPrefix("myapp"),          // Text format prefix
+    WithTimeFormat("2006-01-02"), // Custom time format
+)
+```
+
+## Text Format Output
+
+```
+2026-01-17 15:30:45 INFO hello world
+2026-01-17 15:30:45 INFO user logged in user_id=123 action=login
+```
+
+## JSON Format Output
+
+```json
+{"time":"2026-01-17T15:30:45Z","level":"INFO","message":"hello world"}
+{"time":"2026-01-17T15:30:45Z","level":"INFO","message":"user logged in","user_id":123,"action":"login"}
+```
+
+## Global Functions
+
+```go
+import "gitea.loveuer.com/loveuer/upkg/logger"
+
+func Debug(format string, args ...)
+func Info(format string, args ...)
+func Warn(format string, args ...)
+func Error(format string, args ...)
+func Fatal(format string, args ...)
+func Panic(format string, args ...)
+
+func DebugCtx(ctx context.Context, format string, args ...)
+func InfoCtx(ctx context.Context, format string, args ...)
+func WarnCtx(ctx context.Context, format string, args ...)
+func ErrorCtx(ctx context.Context, format string, args ...)
+func FatalCtx(ctx context.Context, format string, args ...)
+func PanicCtx(ctx context.Context, format string, args ...)
+
+func DebugField(message string, keyValues ...interface{})
+func InfoField(message string, keyValues ...interface{})
+func WarnField(message string, keyValues ...interface{})
+func ErrorField(message string, keyValues ...interface{})
+func FatalField(message string, keyValues ...interface{})
+func PanicField(message string, keyValues ...interface{})
+```