Categorygithub.com/davidwalter0/go-cfgpkglogger
package
3.0.0+incompatible
Repository: https://github.com/davidwalter0/go-cfg.git
Documentation: pkg.go.dev
Overview
Dependencies
9
Dependents
0

# README

#+TITLE: Logger Package Documentation #+AUTHOR: go-cfg autocfg logger #+DATE: [2025-06-20 Thu] #+OPTIONS: toc:2 num:t

  • Overview

The logger package provides a structured, leveled logging system for the go-cfg library. It's designed for simplicity, performance, and seamless integration with autocfg configuration management.

  • Current Features

** Log Levels The logger supports five hierarchical log levels:

| Level | Description | Use Case | |-------+------------------------------------------------+------------------------------------| | DEBUG | Detailed diagnostic information | Development debugging | | INFO | General application flow information | Normal operation tracking | | WARN | Warning conditions that don't halt execution | Potentially harmful situations | | ERROR | Error conditions that allow continued operation | Recoverable errors | | FATAL | Critical errors that terminate the application | Unrecoverable system failures |

** Structured Logging

  • =WithField(key, value)= - Add single field
  • =WithFields(map[string]interface{})= - Add multiple fields
  • Field chaining supported for complex contexts

** Configuration Options

*** Output Destinations

  • =SetOutput(io.Writer)= - Configure output destination
  • Default: =os.Stdout=
  • Supports files, buffers, network connections

*** Timestamp Formatting

  • =SetTimeFormat(format)= - Configure timestamp format
  • Default: RFC3339 (=2006-01-02T15:04:05Z07:00=)
  • Supports any Go time format

*** Log Level Control

  • =SetLevel(Level)= - Set minimum logging level
  • =ParseLevel(string)= - Parse level from configuration
  • Global and per-instance level control
  • Usage Examples

** Basic Logging #+begin_src go :tangle examples/basic_logging.go :results org :main no :package main :mkdirp yes :tangle-mode o0644 package main

import ( "github.com/davidwalter0/go-cfg/pkg/logger" )

func main() { // Global logger functions logger.Info("Application started") logger.Error("Database connection failed: %v", err)

// Create custom logger instance
log := logger.New()
log.SetLevel(logger.DebugLevel)
log.Debug("Debug information")

} #+end_src

** Structured Logging #+begin_src go :tangle examples/structured_logging.go :results org :main no :package main :mkdirp yes :tangle-mode o0644 package main

import ( "github.com/davidwalter0/go-cfg/pkg/logger" )

func handleRequest(userID int, method, path string) { log := logger.New()

// Single field
log.WithField("user_id", userID).Info("User request received")

// Multiple fields
log.WithFields(map[string]interface{}{
    "method":     method,
    "path":       path,
    "user_id":    userID,
    "request_id": generateRequestID(),
}).Info("Processing HTTP request")

// Field chaining
log.WithField("component", "auth").
    WithField("action", "login").
    Info("Authentication attempt")

} #+end_src

** Configuration Integration #+begin_src go :tangle examples/config_integration.go :results org :main no :package main :mkdirp yes :tangle-mode o0644 package main

import ( "log"

"github.com/davidwalter0/go-cfg"
"github.com/davidwalter0/go-cfg/pkg/logger"

)

type ServerConfig struct { LogLevel string default:"info" json:"log_level" LogFile string json:"log_file" Debug bool default:"false" json:"debug" }

func main() { var config ServerConfig

// Parse configuration
if err := cfg.Flags(&config); err != nil {
    log.Fatalf("Configuration error: %v", err)
}

// Configure logger from config
level, err := logger.ParseLevel(config.LogLevel)
if err != nil {
    log.Fatalf("Invalid log level: %v", err)
}

logger.SetGlobalLevel(level)

// Configure output destination
if config.LogFile != "" {
    file, err := os.OpenFile(config.LogFile, 
        os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
    if err != nil {
        log.Fatalf("Cannot open log file: %v", err)
    }
    defer file.Close()
    logger.SetGlobalOutput(file)
}

logger.Info("Server configured with log level: %s", config.LogLevel)

} #+end_src

  • Current Limitations

** Missing Features The current implementation lacks several advanced features:

*** Output Formats

  • ❌ JSON structured output
  • ❌ Key-value structured format
  • ❌ Custom formatters
  • ✅ Plain text only (current)

*** Caller Information

  • ❌ Source file and line number
  • ❌ Function name tracking
  • ❌ Stack trace support

*** Advanced Configuration

  • ❌ Log rotation
  • ❌ Async logging
  • ❌ Log sampling/throttling
  • Enhancement Roadmap

** Phase 1: Output Formats

  • JSON formatter implementation
  • Structured key-value formatter
  • Configurable formatter interface

** Phase 2: Caller Information

  • Runtime caller detection
  • Configurable caller depth
  • Short vs full path options

** Phase 3: Advanced Features

  • Async logging with channels
  • Log rotation integration
  • Performance optimizations
  • Integration with go-cfg

The logger integrates seamlessly with go-cfg's configuration system:

#+begin_src yaml :tangle examples/server_config.yaml :mkdirp yes :tangle-mode o0644

Configuration file example

log_level: "debug" log_file: "/var/log/myapp.log" debug: true enable_logging: true #+end_src

Environment variables:

  • =LOG_LEVEL= - Set logging level
  • =LOG_FILE= - Set output file path
  • =DEBUG= - Enable debug mode

Command-line flags:

  • =--log-level= - Set logging level
  • =--log-file= - Set output file path
  • =--debug= - Enable debug mode
  • Performance Characteristics

** Benchmarks Current performance metrics from test suite:

| Test Case | Operations/sec | ns/op | Allocations | |-------------------------+----------------+-------+-------------| | Basic Info logging | ~1M ops/sec | ~1000 | Minimal | | WithField logging | ~800K ops/sec | ~1200 | Moderate | | WithFields logging | ~600K ops/sec | ~1600 | Higher |

** Memory Usage

  • Minimal allocations for basic logging
  • Field logging creates new logger instances (immutable)
  • No memory leaks in concurrent usage
  • Thread Safety

The logger is fully thread-safe:

  • Global logger functions are safe for concurrent use
  • Logger instances can be shared across goroutines
  • Field operations create new instances (no shared state mutation)
  • Testing

Comprehensive test coverage includes:

  • Unit tests for all public functions
  • Integration tests with configuration
  • Benchmark tests for performance validation
  • Concurrent usage safety tests

Run tests: #+begin_src bash :tangle test_commands.sh :results org :shebang #!/usr/bin/env bash :mkdirp yes :comments org :padline yes :tangle-mode o0755 #!/usr/bin/env bash

Run all logger tests

go test ./pkg/logger -v

Run benchmarks

go test ./pkg/logger -bench=. -benchmem

Test with race detection

go test ./pkg/logger -race

Coverage report

go test ./pkg/logger -cover -coverprofile=coverage.out go tool cover -html=coverage.out -o coverage.html #+end_src

  • Migration Guide

For projects migrating from standard library =log= package:

** Before (stdlib log) #+begin_src go import "log"

log.Println("Info message") log.Printf("Error: %v", err) #+end_src

** After (go-cfg logger) #+begin_src go import "github.com/davidwalter0/go-cfg/pkg/logger"

logger.Info("Info message") logger.Error("Error: %v", err) #+end_src

** Advanced Migration #+begin_src go // Create logger with context log := logger.New().WithFields(map[string]interface{}{ "component": "auth", "version": "1.2.3", })

log.Info("Service initialized") log.Error("Authentication failed: %v", err) #+end_src