130 lines
3.4 KiB
Markdown
130 lines
3.4 KiB
Markdown
# 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{})
|
|
```
|