feat(log): Formatted console logging with file output

README.md

@@ -22,6 +22,8 @@ go get git.secnex.io/secnex/masterlog
 
 ## Quick Start
 
+### Basic Usage
+
 ```go
 package main
 
@@ -30,7 +32,7 @@ import (
 )
 
 func main() {
-    // Simple logging
+    // Simple logging using the global logger
     masterlog.Info("Hello, World!")
     
     // Logging with fields
@@ -47,6 +49,45 @@ func main() {
 2025-11-10T05:06:02+01:00 INF main.go:12 > User logged in user_id=12345 ip=192.168.1.1 go_version=go1.25.3 pid=12345
 ```
 
+### Configuring the Global Logger
+
+Configure the global logger once at application startup:
+
+```go
+package main
+
+import (
+    "git.secnex.io/secnex/masterlog"
+)
+
+func main() {
+    // Configure global logger at startup
+    masterlog.SetLevel(masterlog.LevelDebug)
+    
+    // Add file writer
+    fileWriter, _ := masterlog.NewFileWriter("app.log")
+    defer fileWriter.Close()
+    masterlog.AddWriter(fileWriter)
+    
+    // Add JSON encoder
+    masterlog.AddEncoder(&masterlog.JSONEncoder{})
+    
+    // Configure pseudonymization
+    pseudonymizer := masterlog.NewPseudonymizerFromEnv("LOG_SECRET")
+    masterlog.SetPseudonymizer(pseudonymizer)
+    masterlog.AddSensitiveFields("user_id", "email", "ip")
+    
+    // Now all package-level functions use the configured global logger
+    masterlog.Info("Application started")
+    masterlog.Debug("Debug message")
+}
+```
+
+**Benefits:**
+- Configure once, use everywhere
+- No need to pass logger instances around
+- Simple and convenient for most use cases
+
 ## Table of Contents
 
 - [Log Levels](#log-levels)
@@ -211,6 +252,22 @@ logger.Info("Console log")
 
 Writes log entries to a file.
 
+**Using with global logger (recommended):**
+
+```go
+// Add file writer to global logger
+fileWriter, err := masterlog.NewFileWriter("app.log")
+if err != nil {
+    log.Fatal(err)
+}
+defer fileWriter.Close()
+
+masterlog.AddWriter(fileWriter)
+masterlog.Info("File log")  // Uses global logger
+```
+
+**Using with custom logger:**
+
 ```go
 logger := masterlog.New()
 fileWriter, err := masterlog.NewFileWriter("app.log")
@@ -239,9 +296,42 @@ logger.AddWriter(fileWriter)
 logger.Info("Multi-destination log")
 ```
 
-## Custom Logger Instances
+## Global Logger vs Custom Instances
 
-Create custom logger instances with specific configurations:
+MasterLog provides two ways to use logging:
+
+### Global Logger (Recommended for Most Cases)
+
+The global logger is pre-configured and ready to use. Configure it once at startup:
+
+```go
+func main() {
+    // Configure global logger at startup
+    masterlog.SetLevel(masterlog.LevelDebug)
+    
+    // Add file writer
+    fileWriter, _ := masterlog.NewFileWriter("app.log")
+    defer fileWriter.Close()
+    masterlog.AddWriter(fileWriter)
+    
+    // Add JSON encoder
+    masterlog.AddEncoder(&masterlog.JSONEncoder{})
+    
+    // Use package-level functions anywhere in your code
+    masterlog.Info("This uses the global logger")
+    masterlog.Debug("No need to pass logger instances around")
+}
+```
+
+**Advantages:**
+- Simple and convenient
+- No need to pass logger instances
+- Configure once, use everywhere
+- Perfect for most applications
+
+### Custom Logger Instances
+
+Create custom logger instances when you need different configurations for different components:
 
 ```go
 // Create logger with custom level
@@ -258,6 +348,37 @@ logger.AddWriter(fileWriter)
 logger.Info("Custom logger example")
 ```
 
+**Use Cases:**
+- Different log levels for different components
+- Separate log files for different modules
+- Different encoders for different outputs
+- Component-specific pseudonymization rules
+
+### Replacing the Global Logger
+
+You can also replace the global logger with a custom instance:
+
+```go
+// Create and configure a custom logger
+customLogger := masterlog.New(masterlog.LevelTrace)
+customLogger.AddEncoder(&masterlog.JSONEncoder{})
+
+// Replace the global logger
+masterlog.SetDefaultLogger(customLogger)
+
+// Now all package-level functions use your custom logger
+masterlog.Info("Uses the custom logger")
+```
+
+### Getting the Global Logger
+
+Access the global logger instance directly if needed:
+
+```go
+globalLogger := masterlog.GetDefaultLogger()
+globalLogger.AddWriter(fileWriter)
+```
+
 ## Data Pseudonymization
 
 MasterLog includes built-in support for deterministic pseudonymization of sensitive data using HMAC-SHA256. This allows you to:
@@ -415,6 +536,8 @@ func AddEncoder(encoder Encoder)
 func SetPseudonymizer(pseudonymizer *Pseudonymizer)
 func AddSensitiveField(fieldName string)
 func AddSensitiveFields(fieldNames ...string)
+func SetDefaultLogger(logger *MasterLogger)
+func GetDefaultLogger() *MasterLogger
 ```
 
 ### Logger Methods