global.go

// Package log provides a structured logging system built on top of Zap.
package log

import "go.uber.org/zap"

// Global logging functions
//
// This file provides convenience functions that mirror the methods of zap.Logger
// but operate on the global logger instance (zap.L()). These functions allow for
// direct logging without needing to create a logger instance or use the context-aware
// logging functionality.
//
// These functions are useful for:
// - Simple applications that don't need context-aware logging
// - Legacy code that can't easily be refactored to use context
// - Initialization code that runs before a context is available
// - Utility functions that don't receive a context parameter
//
// For most application code, the context-aware logging functions (Ctx, Stash)
// are recommended as they provide better traceability and correlation of logs.

// Debug logs debug-level messages using the global logger.
// Debug logs are typically verbose and used for detailed troubleshooting information.
//
// Parameters:
//   - msg: The message to log
//   - fields: Additional structured context to add to the log
//
// Example:
//
//	log.Debug("Connection established", zap.String("remote_addr", conn.RemoteAddr().String()))
func Debug(msg string, fields ...zap.Field) {
	zap.L().Debug(msg, fields...)
}

// Info logs info-level messages using the global logger.
// Info logs are used for general operational information about the normal functioning of the application.
//
// Parameters:
//   - msg: The message to log
//   - fields: Additional structured context to add to the log
//
// Example:
//
//	log.Info("Server started", zap.Int("port", 8080))
func Info(msg string, fields ...zap.Field) {
	zap.L().Info(msg, fields...)
}

// Warn logs warning-level messages using the global logger.
// Warn logs indicate potential issues or unexpected behavior that doesn't prevent the application from working.
//
// Parameters:
//   - msg: The message to log
//   - fields: Additional structured context to add to the log
//
// Example:
//
//	log.Warn("Configuration value deprecated", zap.String("key", "old_setting"))
func Warn(msg string, fields ...zap.Field) {
	zap.L().Warn(msg, fields...)
}

// Error logs error-level messages using the global logger.
// Error logs indicate issues that prevented some operation from completing successfully.
//
// Parameters:
//   - msg: The message to log
//   - fields: Additional structured context to add to the log
//
// Example:
//
//	if err != nil {
//	    log.Error("Failed to connect to database", zap.Error(err))
//	}
func Error(msg string, fields ...zap.Field) {
	zap.L().Error(msg, fields...)
}

// DPanic logs development-panic-level messages using the global logger.
// If the global logger is in development mode, this will also panic after logging.
// This level is useful for catching errors that shouldn't occur during development.
//
// Parameters:
//   - msg: The message to log
//   - fields: Additional structured context to add to the log
//
// Example:
//
//	if invariantViolated {
//	    log.DPanic("Invariant violated", zap.String("details", "expected X but got Y"))
//	}
func DPanic(msg string, fields ...zap.Field) {
	zap.L().DPanic(msg, fields...)
}

// Panic logs panic-level messages using the global logger and then panics.
// This will cause the application to halt with a panic after logging the message.
//
// Parameters:
//   - msg: The message to log
//   - fields: Additional structured context to add to the log
//
// Example:
//
//	if criticalError != nil {
//	    log.Panic("Critical error occurred", zap.Error(criticalError))
//	}
func Panic(msg string, fields ...zap.Field) {
	zap.L().Panic(msg, fields...)
}

// Fatal logs fatal-level messages using the global logger and then calls os.Exit(1).
// This will cause the application to halt immediately, bypassing any deferred functions.
//
// Parameters:
//   - msg: The message to log
//   - fields: Additional structured context to add to the log
//
// Example:
//
//	if err := startServer(); err != nil {
//	    log.Fatal("Failed to start server", zap.Error(err))
//	}
func Fatal(msg string, fields ...zap.Field) {
	zap.L().Fatal(msg, fields...)
}

// Sync flushes any buffered log entries from the global logger to their destination.
// This method should typically be called before application termination to ensure
// all log entries are written, especially when using buffered writers.
//
// Returns an error if the global logger's Sync method returns an error.
//
// Example:
//
//	func main() {
//	    // Application code...
//
//	    // Before exiting, flush any buffered logs
//	    defer log.Sync()
//	}
func Sync() error {
	return zap.L().Sync()
}

// With creates a new zap.Logger with additional fields attached to the global logger.
// These fields will be included in all subsequent log entries made with the returned logger.
//
// Parameters:
//   - fields: The zap.Field values to attach to the new logger
//
// Returns a new zap.Logger with the specified fields attached.
//
// Example:
//
//	// Create a logger for a specific component
//	componentLogger := log.With(zap.String("component", "user_service"))
//
//	// Later logs will include the component field
//	componentLogger.Info("Operation started")
func With(fields ...zap.Field) *zap.Logger {
	return zap.L().With(fields...)
}