log

README

Log Library

log is a structured logging wrapper based on log/slog and zap.

Features

• Standard API: Built on top of log/slog.
• High Performance: Powered by uber-go/zap.
• Flexible Configuration:
  • Formats: JSON, Text.
  • Outputs: Stdout, Stderr, File (with rotation).
  • Levels: Dynamic level adjustment.
• Context Aware: Automatic injection/extraction of trace_id, request_id, user_id.
• Rich Details: Configurable caller and stacktrace reporting.

Usage

package main

import (
	"context"
	"log/slog"

	"github.com/fuguiw/fg-lib/log"
)

func main() {
	// Initialize
	opts := log.DefaultOptions()
	opts.Level = slog.LevelDebug
	opts.Format = log.FormatJSON
	
	if err := log.Init(opts); err != nil {
		panic(err)
	}

	// Use slog as usual
	slog.Info("Hello World", "key", "value")

	// Context with Trace ID
	ctx := log.WithTraceID(context.Background(), "trace-123")
	slog.InfoContext(ctx, "Processing request") // output includes trace_id

	// Dynamic Level
	log.SetLevel(slog.LevelInfo)
}

Documentation

Index

• Constants
• func Init(opts *Options) error
• func SetLevel(l slog.Level)
• func WithRequestID(ctx context.Context, reqID string) context.Context
• func WithTraceID(ctx context.Context, traceID string) context.Context
• func WithUserID(ctx context.Context, userID string) context.Context
• type Format
• type Options
  • func DefaultOptions() *Options
• type Output
• type ZapHandler
  • func NewZapHandler(opts *Options, level zap.AtomicLevel) *ZapHandler
  • func (h *ZapHandler) Handle(ctx context.Context, record slog.Record) error

Constants

const (
	TraceIDKey ctxKey = "trace_id"
	ReqIDKey   ctxKey = "request_id"
	UserIDKey  ctxKey = "user_id"
)

Functions

func Init

func Init(opts *Options) error

Init initializes the global logger with the provided options.

func SetLevel

func SetLevel(l slog.Level)

SetLevel dynamically sets the log level.

func WithRequestID

func WithRequestID(ctx context.Context, reqID string) context.Context

func WithTraceID

func WithTraceID(ctx context.Context, traceID string) context.Context

func WithUserID

func WithUserID(ctx context.Context, userID string) context.Context

Types

type Format

type Format string

const (
	FormatJSON Format = "json"
	FormatText Format = "text"
)

type Options

type Options struct {
	// Level is the minimum log level to output.
	Level slog.Level

	// Format specifies the output format (json or text).
	Format Format

	// Output specifies where to write logs (stdout, stderr, or file).
	Output Output

	// FilePath is the path to the log file (required if Output is "file").
	FilePath string

	// Rotation configuration for file output.
	MaxSize    int  // megabytes
	MaxBackups int  // number of files
	MaxAge     int  // days
	Compress   bool // compress rotated files

	// EnableCaller enables caller reporting.
	EnableCaller bool

	// EnableStack enables stack trace recording.
	EnableStack bool
}

func DefaultOptions

func DefaultOptions() *Options

type Output

type Output string

const (
	OutputStdout Output = "stdout"
	OutputStderr Output = "stderr"
	OutputFile   Output = "file"
)

type ZapHandler

type ZapHandler struct {
	slog.Handler
	// contains filtered or unexported fields
}

func NewZapHandler

func NewZapHandler(opts *Options, level zap.AtomicLevel) *ZapHandler

func (*ZapHandler) Handle

func (h *ZapHandler) Handle(ctx context.Context, record slog.Record) error

Handle overrides the underlying handler's Handle method to inject context fields.