docs: add example programs for common usage patterns

Adds four focused examples in examples/ directory:
- basic: drop-in logger with web UI
- namespaces: namespace-based logging by component
- client: programmatic log client with filtering
- log-levels: all log levels and filtering

Fixes #7

README.md

@@ -15,6 +15,7 @@ A real-time log viewer with WebSocket support and namespace filtering, written i
 - **Namespace filtering**: Subscribe to specific namespaces via WebSocket
 - **Frontend namespace selector**: Filter logs by namespace in the web UI
 - **Namespace API**: GET `/api/namespaces` to list all active namespaces
+- **Colored terminal output**: Log levels are color-coded in terminal (no external packages)
 
 ## Features
 
@@ -188,6 +189,40 @@ ws://localhost:8080/ws?namespaces=api,database  # Multiple namespaces
 - **Color Coding**: Different log levels are color-coded
 - **Reconnect**: Reconnect WebSocket with new namespace filter
 
+## Terminal Colors
+
+Log output to stderr is automatically colorized when writing to a terminal. Colors are disabled when output is piped or redirected to a file.
+
+### Color Scheme
+
+| Level  | Color        |
+|--------|--------------|
+| TRACE  | Gray         |
+| DEBUG  | Cyan         |
+| INFO   | Green        |
+| NOTICE | Blue         |
+| WARN   | Yellow       |
+| ERROR  | Red          |
+| PANIC  | Bold Red     |
+| FATAL  | Bold Red     |
+
+### Controlling Colors
+
+```go
+// Disable colors (e.g., for CI/CD or file output)
+logger.SetColorEnabled(false)
+
+// Enable colors explicitly
+logger.SetColorEnabled(true)
+
+// Check current state
+if logger.ColorEnabled() {
+    // colors are on
+}
+```
+
+Colors are implemented using standard ANSI escape codes with no external dependencies.
+
 ## Migration from v1
 
 ### Import Path

examples/basic/main.go

@@ -0,0 +1,36 @@
+// Example: basic usage of log-socket as a drop-in logger.
+//
+// This demonstrates using the package-level logging functions,
+// which work similarly to the standard library's log package.
+package main
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/taigrr/log-socket/v2/browser"
+	logger "github.com/taigrr/log-socket/v2/log"
+	"github.com/taigrr/log-socket/v2/ws"
+)
+
+func main() {
+	defer logger.Flush()
+
+	// Set the minimum log level (default is LTrace, showing everything)
+	logger.SetLogLevel(logger.LDebug)
+
+	// Package-level functions log to the "default" namespace
+	logger.Info("Application starting up")
+	logger.Debug("Debug mode enabled")
+	logger.Warnf("Config file not found at %s, using defaults", "/etc/app/config.yaml")
+	logger.Errorf("Failed to connect to database: %s", "connection refused")
+
+	// Print/Printf/Println are aliases for Info
+	logger.Println("This is equivalent to Infoln")
+
+	// Start the web UI so you can view logs at http://localhost:8080
+	http.HandleFunc("/ws", ws.LogSocketHandler)
+	http.HandleFunc("/", browser.LogSocketViewHandler)
+	fmt.Println("Log viewer available at http://localhost:8080")
+	logger.Fatal(http.ListenAndServe("0.0.0.0:8080", nil))
+}

examples/client/main.go

@@ -0,0 +1,63 @@
+// Example: programmatic log client with namespace filtering.
+//
+// This shows how to create a Client that receives log entries
+// programmatically, optionally filtered to specific namespaces.
+// Useful for building custom log processors, alerting, or forwarding.
+package main
+
+import (
+	"fmt"
+	"time"
+
+	logger "github.com/taigrr/log-socket/v2/log"
+)
+
+func main() {
+	defer logger.Flush()
+
+	// Create a client that receives ALL log entries
+	allLogs := logger.CreateClient()
+	allLogs.SetLogLevel(logger.LInfo)
+
+	// Create a client that only receives "database" and "auth" logs
+	securityLogs := logger.CreateClient("database", "auth")
+	securityLogs.SetLogLevel(logger.LWarn) // Only warnings and above
+
+	dbLog := logger.NewLogger("database")
+	authLog := logger.NewLogger("auth")
+	apiLog := logger.NewLogger("api")
+
+	// Process all logs
+	go func() {
+		for {
+			entry := allLogs.Get()
+			fmt.Printf("[ALL] %s [%s] %s: %s\n",
+				entry.Timestamp.Format(time.TimeOnly),
+				entry.Namespace, entry.Level, entry.Output)
+		}
+	}()
+
+	// Process only security-relevant warnings/errors
+	go func() {
+		for {
+			entry := securityLogs.Get()
+			if entry.Level == "ERROR" || entry.Level == "WARN" {
+				fmt.Printf("🚨 SECURITY ALERT [%s] %s: %s\n",
+					entry.Namespace, entry.Level, entry.Output)
+			}
+		}
+	}()
+
+	// Generate some logs
+	for i := 0; i < 5; i++ {
+		apiLog.Info("API request processed")
+		dbLog.Info("Query executed successfully")
+		dbLog.Warn("Connection pool running low")
+		authLog.Error("Brute force attempt detected")
+		time.Sleep(1 * time.Second)
+	}
+
+	// Clean up clients when done
+	allLogs.Destroy()
+	securityLogs.Destroy()
+}

examples/log-levels/main.go

@@ -0,0 +1,48 @@
+// Example: log level filtering and all available levels.
+//
+// log-socket supports 8 log levels from TRACE (most verbose)
+// to FATAL (least verbose). Setting a log level filters out
+// everything below it.
+package main
+
+import (
+	"fmt"
+
+	logger "github.com/taigrr/log-socket/v2/log"
+)
+
+func main() {
+	defer logger.Flush()
+
+	fmt.Println("=== All log levels (TRACE and above) ===")
+	logger.SetLogLevel(logger.LTrace)
+
+	logger.Trace("Detailed execution trace — variable x = 42")
+	logger.Debug("Processing request for user_id=123")
+	logger.Info("Server started on :8080")
+	logger.Notice("Configuration reloaded")
+	logger.Warn("Disk usage at 85%")
+	logger.Error("Failed to send email: SMTP timeout")
+	// logger.Panic("...") — would panic
+	// logger.Fatal("...") — would os.Exit(1)
+
+	fmt.Println("\n=== Formatted variants ===")
+	logger.Infof("Request took %dms", 42)
+	logger.Warnf("Retrying in %d seconds (attempt %d/%d)", 5, 2, 3)
+	logger.Errorf("HTTP %d: %s", 503, "Service Unavailable")
+
+	fmt.Println("\n=== Only WARN and above ===")
+	logger.SetLogLevel(logger.LWarn)
+
+	logger.Debug("This will NOT appear")
+	logger.Info("This will NOT appear either")
+	logger.Warn("This WILL appear")
+	logger.Error("This WILL appear too")
+
+	fmt.Println("\n=== Per-logger levels via namespaced loggers ===")
+	logger.SetLogLevel(logger.LTrace) // Reset global
+
+	appLog := logger.NewLogger("app")
+	appLog.Info("Namespaced loggers inherit the global output but tag entries")
+	appLog.Warnf("Something needs attention in the %s subsystem", "app")
+}

examples/namespaces/main.go

@@ -0,0 +1,73 @@
+// Example: namespace-based logging for organizing logs by component.
+//
+// Namespaces let you tag log entries by subsystem (api, database, auth, etc.)
+// and filter them in the web UI or via programmatic clients.
+package main
+
+import (
+	"fmt"
+	"math/rand"
+	"net/http"
+	"time"
+
+	"github.com/taigrr/log-socket/v2/browser"
+	logger "github.com/taigrr/log-socket/v2/log"
+	"github.com/taigrr/log-socket/v2/ws"
+)
+
+func main() {
+	defer logger.Flush()
+
+	// Create loggers for different subsystems
+	apiLog := logger.NewLogger("api")
+	dbLog := logger.NewLogger("database")
+	authLog := logger.NewLogger("auth")
+	cacheLog := logger.NewLogger("cache")
+
+	// Simulate application activity
+	go func() {
+		for {
+			apiLog.Infof("GET /api/users — 200 OK (%dms)", rand.Intn(200))
+			apiLog.Debugf("Request headers: Accept=application/json")
+			time.Sleep(1 * time.Second)
+		}
+	}()
+
+	go func() {
+		for {
+			dbLog.Infof("SELECT * FROM users — %d rows", rand.Intn(100))
+			if rand.Float64() < 0.3 {
+				dbLog.Warn("Slow query detected (>500ms)")
+			}
+			time.Sleep(2 * time.Second)
+		}
+	}()
+
+	go func() {
+		for {
+			if rand.Float64() < 0.7 {
+				authLog.Info("User login successful")
+			} else {
+				authLog.Error("Failed login attempt from 192.168.1.42")
+			}
+			time.Sleep(3 * time.Second)
+		}
+	}()
+
+	go func() {
+		for {
+			cacheLog.Tracef("Cache hit ratio: %.1f%%", rand.Float64()*100)
+			if rand.Float64() < 0.1 {
+				cacheLog.Warn("Cache eviction triggered")
+			}
+			time.Sleep(5 * time.Second)
+		}
+	}()
+
+	// The /api/namespaces endpoint lists all active namespaces
+	http.HandleFunc("/ws", ws.LogSocketHandler)
+	http.HandleFunc("/api/namespaces", ws.NamespacesHandler)
+	http.HandleFunc("/", browser.LogSocketViewHandler)
+	fmt.Println("Log viewer with namespace filtering at http://localhost:8080")
+	logger.Fatal(http.ListenAndServe("0.0.0.0:8080", nil))
+}

go.mod

@@ -1,5 +1,5 @@
 module github.com/taigrr/log-socket/v2
 
-go 1.25.4
+go 1.25.6
 
 require github.com/gorilla/websocket v1.5.3

log/color.go

@@ -0,0 +1,99 @@
+package log
+
+import (
+	"os"
+	"sync"
+)
+
+// ANSI color codes for terminal output
+const (
+	colorReset  = "\033[0m"
+	colorRed    = "\033[31m"
+	colorGreen  = "\033[32m"
+	colorYellow = "\033[33m"
+	colorBlue   = "\033[34m"
+	colorPurple = "\033[35m"
+	colorCyan   = "\033[36m"
+	colorWhite  = "\033[37m"
+	colorGray   = "\033[90m"
+
+	// Bold variants
+	colorBoldRed    = "\033[1;31m"
+	colorBoldYellow = "\033[1;33m"
+	colorBoldWhite  = "\033[1;37m"
+)
+
+var (
+	colorEnabled     = true
+	colorEnabledOnce sync.Once
+	colorMux         sync.RWMutex
+)
+
+// SetColorEnabled enables or disables colored output for stderr logging.
+// By default, color is enabled when stderr is a terminal.
+func SetColorEnabled(enabled bool) {
+	colorMux.Lock()
+	colorEnabled = enabled
+	colorMux.Unlock()
+}
+
+// ColorEnabled returns whether colored output is currently enabled.
+func ColorEnabled() bool {
+	colorMux.RLock()
+	defer colorMux.RUnlock()
+	return colorEnabled
+}
+
+// isTerminal checks if the given file descriptor is a terminal.
+// This is a simple heuristic that works on Unix-like systems.
+func isTerminal(f *os.File) bool {
+	stat, err := f.Stat()
+	if err != nil {
+		return false
+	}
+	return (stat.Mode() & os.ModeCharDevice) != 0
+}
+
+// initColorEnabled sets the default color state based on whether stderr is a terminal.
+func initColorEnabled() {
+	colorEnabledOnce.Do(func() {
+		colorEnabled = isTerminal(os.Stderr)
+	})
+}
+
+// levelColor returns the ANSI color code for a given log level.
+func levelColor(level Level) string {
+	switch level {
+	case LTrace:
+		return colorGray
+	case LDebug:
+		return colorCyan
+	case LInfo:
+		return colorGreen
+	case LNotice:
+		return colorBlue
+	case LWarn:
+		return colorYellow
+	case LError:
+		return colorRed
+	case LPanic:
+		return colorBoldRed
+	case LFatal:
+		return colorBoldRed
+	default:
+		return colorReset
+	}
+}
+
+// colorize wraps text with ANSI color codes if color is enabled.
+func colorize(text string, color string) string {
+	if !ColorEnabled() {
+		return text
+	}
+	return color + text + colorReset
+}
+
+// colorizeLevelText returns the level string with appropriate color.
+func colorizeLevelText(level string, lvl Level) string {
+	return colorize(level, levelColor(lvl))
+}

log/log.go

@@ -22,7 +22,8 @@ var (
 
 func init() {
 	namespaces = make(map[string]bool)
-	stderrClient = CreateClient(DefaultNamespace)
+	initColorEnabled()
+	stderrClient = CreateClient()
 	stderrClient.SetLogLevel(LTrace)
 	stderrFinished = make(chan bool, 1)
 	go stderrClient.logStdErr()
@@ -31,7 +32,10 @@ func init() {
 func (c *Client) logStdErr() {
 	for e := range c.writer {
 		if e.level >= c.LogLevel && c.matchesNamespace(e.Namespace) {
-			fmt.Fprintf(os.Stderr, "%s\t%s\t[%s]\t%s\t%s\n", e.Timestamp.String(), e.Level, e.Namespace, e.Output, e.File)
+			levelStr := colorizeLevelText(e.Level, e.level)
+			nsStr := colorize("["+e.Namespace+"]", colorPurple)
+			fileStr := colorize(e.File, colorGray)
+			fmt.Fprintf(os.Stderr, "%s\t%s\t%s\t%s\t%s\n", e.Timestamp.String(), levelStr, nsStr, e.Output, fileStr)
 		}
 	}
 	stderrFinished <- true
@@ -70,19 +74,19 @@ func Flush() {
 }
 
 func (c *Client) Destroy() error {
-	var otherClients []*Client
 	if !c.initialized {
 		panic(errors.New("cannot delete uninitialized client, did you use CreateClient?"))
 	}
 	sliceTex.Lock()
-	c.writer = nil
 	c.initialized = false
+	var otherClients []*Client
 	for _, x := range clients {
-		if x.initialized {
+		if x != c && x.initialized {
 			otherClients = append(otherClients, x)
 		}
 	}
 	clients = otherClients
+	c.writer = nil
 	sliceTex.Unlock()
 	return nil
 }
@@ -103,6 +107,9 @@ func createLog(e Entry) {
 	sliceTex.Lock()
 	for _, c := range clients {
 		func(c *Client, e Entry) {
+			if c.writer == nil || !c.initialized {
+				return
+			}
 			// Filter by namespace if client has filters specified
 			if !c.matchesNamespace(e.Namespace) {
 				return
@@ -417,7 +424,7 @@ func Panic(args ...any) {
 		Namespace: DefaultNamespace,
 	}
 	createLog(e)
-	if len(args) >= 0 {
+	if len(args) > 0 {
 		switch args[0].(type) {
 		case error:
 			panic(args[0])
@@ -441,7 +448,7 @@ func Panicf(format string, args ...any) {
 		Namespace: DefaultNamespace,
 	}
 	createLog(e)
-	if len(args) >= 0 {
+	if len(args) > 0 {
 		switch args[0].(type) {
 		case error:
 			panic(args[0])
@@ -464,7 +471,7 @@ func Panicln(args ...any) {
 		Namespace: DefaultNamespace,
 	}
 	createLog(e)
-	if len(args) >= 0 {
+	if len(args) > 0 {
 		switch args[0].(type) {
 		case error:
 			panic(args[0])

log/logger.go

@@ -28,7 +28,7 @@ func (l Logger) Trace(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "TRACE",
 		level:     LTrace,
 		Namespace: l.Namespace,
@@ -42,7 +42,7 @@ func (l Logger) Tracef(format string, args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "TRACE",
 		level:     LTrace,
 		Namespace: l.Namespace,
@@ -56,7 +56,7 @@ func (l Logger) Traceln(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "TRACE",
 		level:     LTrace,
 		Namespace: l.Namespace,
@@ -70,7 +70,7 @@ func (l Logger) Debug(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "DEBUG",
 		level:     LDebug,
 		Namespace: l.Namespace,
@@ -84,7 +84,7 @@ func (l Logger) Debugf(format string, args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "DEBUG",
 		level:     LDebug,
 		Namespace: l.Namespace,
@@ -98,7 +98,7 @@ func (l Logger) Info(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "INFO",
 		level:     LInfo,
 		Namespace: l.Namespace,
@@ -112,7 +112,7 @@ func (l Logger) Infof(format string, args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "INFO",
 		level:     LInfo,
 		Namespace: l.Namespace,
@@ -126,7 +126,7 @@ func (l Logger) Infoln(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "INFO",
 		level:     LInfo,
 		Namespace: l.Namespace,
@@ -140,7 +140,7 @@ func (l Logger) Notice(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "NOTICE",
 		level:     LNotice,
 		Namespace: l.Namespace,
@@ -154,7 +154,7 @@ func (l Logger) Noticef(format string, args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "NOTICE",
 		level:     LNotice,
 		Namespace: l.Namespace,
@@ -168,7 +168,7 @@ func (l Logger) Noticeln(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "NOTICE",
 		level:     LNotice,
 		Namespace: l.Namespace,
@@ -182,7 +182,7 @@ func (l Logger) Warn(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "WARN",
 		level:     LWarn,
 		Namespace: l.Namespace,
@@ -196,7 +196,7 @@ func (l Logger) Warnf(format string, args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "WARN",
 		level:     LWarn,
 		Namespace: l.Namespace,
@@ -210,7 +210,7 @@ func (l Logger) Warnln(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "WARN",
 		level:     LWarn,
 		Namespace: l.Namespace,
@@ -224,7 +224,7 @@ func (l Logger) Error(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "ERROR",
 		level:     LError,
 		Namespace: l.Namespace,
@@ -238,7 +238,7 @@ func (l Logger) Errorf(format string, args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "ERROR",
 		level:     LError,
 		Namespace: l.Namespace,
@@ -252,7 +252,7 @@ func (l Logger) Errorln(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "ERROR",
 		level:     LError,
 		Namespace: l.Namespace,
@@ -266,13 +266,13 @@ func (l Logger) Panic(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "PANIC",
 		level:     LPanic,
 		Namespace: l.Namespace,
 	}
 	createLog(e)
-	if len(args) >= 0 {
+	if len(args) > 0 {
 		switch args[0].(type) {
 		case error:
 			panic(args[0])
@@ -290,13 +290,13 @@ func (l Logger) Panicf(format string, args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "PANIC",
 		level:     LPanic,
 		Namespace: l.Namespace,
 	}
 	createLog(e)
-	if len(args) >= 0 {
+	if len(args) > 0 {
 		switch args[0].(type) {
 		case error:
 			panic(args[0])
@@ -314,13 +314,13 @@ func (l Logger) Panicln(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "PANIC",
 		level:     LPanic,
 		Namespace: l.Namespace,
 	}
 	createLog(e)
-	if len(args) >= 0 {
+	if len(args) > 0 {
 		switch args[0].(type) {
 		case error:
 			panic(args[0])
@@ -338,7 +338,7 @@ func (l Logger) Fatal(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "FATAL",
 		level:     LFatal,
 		Namespace: l.Namespace,
@@ -354,7 +354,7 @@ func (l Logger) Fatalf(format string, args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "FATAL",
 		level:     LFatal,
 		Namespace: l.Namespace,
@@ -370,7 +370,7 @@ func (l Logger) Fatalln(args ...any) {
 	e := Entry{
 		Timestamp: time.Now(),
 		Output:    output,
-		File:      fileInfo(l.FileInfoDepth),
+		File:      fileInfo(2 + l.FileInfoDepth),
 		Level:     "FATAL",
 		level:     LFatal,
 		Namespace: l.Namespace,