log/doc/getting-started.md

Getting Started

← Back to README | Configuration →

This guide will help you get started with the lixenwraith/log package, from installation through basic usage.

Table of Contents

• Installation
• Basic Usage
• Initialization Methods
• Your First Logger
• Console Output
• Next Steps

Installation

Install the logger package:

go get github.com/lixenwraith/log

For advanced configuration management (optional):

go get github.com/lixenwraith/config

Basic Usage

The logger follows an instance-based design. You create logger instances and call methods on them:

package main

import (
    "github.com/lixenwraith/log"
)

func main() {
    // Create a new logger instance
    logger := log.NewLogger()
    
    // Initialize with defaults
    err := logger.InitWithDefaults()
    if err != nil {
        panic(err)
    }
    defer logger.Shutdown()
    
    // Start logging!
    logger.Info("Application started")
    logger.Debug("Debug mode enabled", "verbose", true)
}

Initialization Methods

The logger provides two initialization methods:

1. Simple Initialization (Recommended for most cases)

Use InitWithDefaults with optional string overrides:

logger := log.NewLogger()
err := logger.InitWithDefaults(
    "directory=/var/log/myapp",
    "level=-4",  // Debug level
    "format=json",
)

2. Configuration-Based Initialization

For complex applications with centralized configuration:

import (
    "github.com/lixenwraith/config"
    "github.com/lixenwraith/log"
)

// Load configuration
cfg := config.New()
cfg.Load("app.toml", os.Args[1:])

// Initialize logger with config
logger := log.NewLogger()
err := logger.Init(cfg, "logging")  // Uses [logging] section in config

Your First Logger

Here's a complete example demonstrating basic logging features:

package main

import (
    "fmt"
    "time"
	
    "github.com/lixenwraith/log"
)

func main() {
    // Create logger
    logger := log.NewLogger()
    
    // Initialize with custom settings
    err := logger.InitWithDefaults(
        "directory=./logs",     // Log directory
        "name=myapp",          // Log file prefix
        "level=0",             // Info level and above
        "format=txt",          // Human-readable format
        "max_size_mb=10",      // Rotate at 10MB
    )
    if err != nil {
        fmt.Printf("Failed to initialize logger: %v\n", err)
        return
    }
    
    // Always shut down gracefully
    defer func() {
        if err := logger.Shutdown(2 * time.Second); err != nil {
            fmt.Printf("Logger shutdown error: %v\n", err)
        }
    }()
    
    // Log at different levels
    logger.Debug("This won't appear (below Info level)")
    logger.Info("Application started", "pid", 12345)
    logger.Warn("Resource usage high", "cpu", 85.5)
    logger.Error("Failed to connect", "host", "db.example.com", "port", 5432)
    
    // Structured logging with key-value pairs
    logger.Info("User action",
        "user_id", 42,
        "action", "login",
        "ip", "192.168.1.100",
        "timestamp", time.Now(),
    )
}

Console Output

For development or container environments, you might want console output:

// Console-only logging (no files)
logger.InitWithDefaults(
    "enable_stdout=true",
    "disable_file=true",
    "level=-4",  // Debug level
)

// Dual output (both file and console)
logger.InitWithDefaults(
    "directory=/var/log/app",
    "enable_stdout=true",
    "stdout_target=stderr",  // Keep stdout clean
)

Next Steps

Now that you have a working logger:

1. Learn about configuration options - Customize behavior for your needs
2. Explore the API - See all available methods
3. Understand logging best practices - Write better logs
4. Check out examples - See real-world usage patterns

Common Patterns

Service Initialization

type Service struct {
    logger *log.Logger
    // other fields...
}

func NewService() (*Service, error) {
    logger := log.NewLogger()
    if err := logger.InitWithDefaults(
        "directory=/var/log/service",
        "name=service",
        "format=json",
    ); err != nil {
        return nil, fmt.Errorf("logger init failed: %w", err)
    }
    
    return &Service{
        logger: logger,
    }, nil
}

func (s *Service) Close() error {
    return s.logger.Shutdown(5 * time.Second)
}

HTTP Middleware

func loggingMiddleware(logger *log.Logger) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            
            // Wrap response writer to capture status
            wrapped := &responseWriter{ResponseWriter: w, status: 200}
            
            next.ServeHTTP(wrapped, r)
            
            logger.Info("HTTP request",
                "method", r.Method,
                "path", r.URL.Path,
                "status", wrapped.status,
                "duration_ms", time.Since(start).Milliseconds(),
                "remote_addr", r.RemoteAddr,
            )
        })
    }
}

---

← Back to README | Configuration →