Add logger package with performance benchmarks

2026-01-17 17:27:33 +08:00
parent f7160ce416
commit 507a67e455
7 changed files with 1105 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -96,6 +96,127 @@ fm.CloseManager()
 - `x-amz-meta-complete`: Upload completion status
 - `x-amz-meta-code`: Unique file code

+## 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
+- **High Performance**: ~727 ns/op for text format, zero-allocation when filtered
+
+### 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
+)
+```
+
+### Performance
+
+| Benchmark | ns/op | B/op | allocs |
+|-----------|-------|------|--------|
+| Info (Text) | 727 | 319 | 6 |
+| Info (JSON) | 1932 | 1026 | 18 |
+| Info (Filtered) | 2 | 0 | 0 |
+| InfoField | 1889 | 1014 | 14 |
+| InfoWithCaller | 1772 | 856 | 11 |
+
+### 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"}
+```
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| `controller/file_manager` | File storage abstraction (local/S3) |
+| `logger` | Structured logging package |
+
 ## License

 MIT