upkg/logger/readme.md

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

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

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

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

log.InfoCtx(ctx, format string, args ...)
// Automatically adds trace_id from ctx as a field

Field Methods

log.InfoField(message string, keyValues ...interface{})
// Example: log.InfoField("user created", "id", 123, "name", "john")

Configuration Options

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

{"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

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{})