logger

Documentation

Overview

Package logger provides a structured logging solution for the Scanitor application. It wraps uber-go/zap logger to provide a simpler interface with support for different verbosity levels and structured logging.

Basic Usage:

logger := logger.NewLogger(logger.Config{
    Verbosity: 0,  // Default level (INFO)
})

// Simple logging
logger.Info("Application started")
logger.Debug("Processing directory") // Only shown with verbosity >= 1
logger.Trace("Detailed operation")   // Only shown with verbosity >= 2

Verbosity Levels:

0: Info, Warn, Error (default)
1: Debug + Level 0
2: Trace + Level 1

Structured Logging:

logger.WithFields(logger.Fields{
    "component": "scanner",
    "path":     "/some/path",
    "count":    42,
}).Info("Directory scan completed")

Output Example (JSON):

{
    "level": "info",
    "ts": "2024-01-20T15:04:05.000Z",
    "message": "Directory scan completed",
    "component": "scanner",
    "path": "/some/path",
    "count": 42
}

Configuration:

type Config struct {
    Verbosity int       // Logging verbosity level
    Output    io.Writer // Output writer (defaults to os.Stderr)
}

Environment Integration:

verbosity := 0
if verbose := os.Getenv("SCANITOR_VERBOSE"); verbose != "" {
    verbosity = len(verbose)  // Each 'v' increases verbosity
}

logger := logger.NewLogger(logger.Config{
    Verbosity: verbosity,
})

Thread Safety:

The logger is safe for concurrent use by multiple goroutines. All logging methods can be called concurrently.

Error Handling Example:

if err != nil {
    logger.WithFields(logger.Fields{
        "error": err.Error(),
        "file":  filename,
    }).Error("Failed to process file")
}

Performance Considerations:

The logger uses uber-go/zap internally, which provides high-performance structured logging. Field allocation is only done when the log level is enabled.

Package logger provides structured logging capabilities for the application.

Index

• type Config
• type Fields
• type Logger
  • func NewLogger(config Config) Logger

Types

type Config

type Config struct {
	// Verbosity determines the logging level:
	// 0: Info, Warn, Error (default)
	// 1: Debug + Level 0
	// 2: Trace + Level 1
	Verbosity int

	// Output specifies where logs should be written.
	// If nil, defaults to os.Stderr
	Output io.Writer
}

Config holds the configuration for creating a new logger instance.

type Fields

type Fields map[string]interface{}

Fields is a type alias for a map of field names to values that can be logged. It's used for structured logging to add context to log messages.

type Logger

type Logger interface {
	// Debug logs a message at debug level. Only shown when verbosity >= 1
	Debug(msg string)

	// Info logs a message at info level. Always shown.
	Info(msg string)

	// Warn logs a message at warn level. Always shown.
	Warn(msg string)

	// Error logs a message at error level. Always shown.
	Error(msg string)

	// Trace logs a message at trace level. Only shown when verbosity >= 2
	Trace(msg string)

	// WithFields returns a new Logger with the given fields added to its context.
	// Fields are included in all subsequent log messages until cleared.
	WithFields(fields Fields) Logger
}

Logger defines the interface for all logging operations. It provides methods for different log levels and structured logging capabilities.

func NewLogger

func NewLogger(config Config) Logger

NewLogger creates a new Logger instance with the given configuration. If no output is specified in the config, os.Stderr will be used.

Example:

logger := NewLogger(Config{
    Verbosity: 1,
})

logger.WithFields(Fields{
    "component": "scanner",
}).Info("Scan started")