enable namespaced logging

Author: taigrr

CRUSH.md

@@ -1,11 +1,26 @@
-# Log Socket
+# Log Socket v2
 
-A real-time log viewer with WebSocket support, written in Go. This tool provides a web-based interface for viewing and filtering logs in real-time.
+A real-time log viewer with WebSocket support and namespace filtering, written in Go.
+
+## What's New in v2
+
+**Breaking Changes:**
+- Module path changed to `github.com/taigrr/log-socket/v2`
+- `CreateClient()` now accepts variadic `namespaces ...string` parameter
+- `Logger` type now includes `Namespace` field
+- New `NewLogger(namespace string)` constructor for namespaced loggers
+
+**New Features:**
+- **Namespace support**: Organize logs by namespace (api, database, auth, etc.)
+- **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
 
 ## Features
 
 - Real-time log streaming via WebSocket
 - Web-based log viewer with filtering capabilities
+- **Namespace-based log organization**
 - Support for multiple log levels (TRACE, DEBUG, INFO, WARN, ERROR, PANIC, FATAL)
 - Color-coded log levels for better visibility
 - Auto-scrolling with toggle option
@@ -16,54 +31,203 @@ A real-time log viewer with WebSocket support, written in Go. This tool provides
 ## Installation
 
 ```bash
-go install github.com/taigrr/log-socket@latest
+go install github.com/taigrr/log-socket/v2@latest
+```
+
+## Quick Start
+
+```go
+package main
+
+import (
+	"net/http"
+	logger "github.com/taigrr/log-socket/v2/log"
+	"github.com/taigrr/log-socket/v2/ws"
+	"github.com/taigrr/log-socket/v2/browser"
+)
+
+func main() {
+	defer logger.Flush()
+	
+	// Set up HTTP handlers
+	http.HandleFunc("/ws", ws.LogSocketHandler)
+	http.HandleFunc("/api/namespaces", ws.NamespacesHandler)
+	http.HandleFunc("/", browser.LogSocketViewHandler)
+	
+	// Use default namespace
+	logger.Info("Application started")
+	
+	// Create namespaced loggers
+	apiLogger := logger.NewLogger("api")
+	dbLogger := logger.NewLogger("database")
+	
+	apiLogger.Info("API server ready")
+	dbLogger.Debug("Database connected")
+	
+	logger.Fatal(http.ListenAndServe(":8080", nil))
+}
+```
+
+## Usage
+
+### Starting the Server
+
+```bash
+log-socket
+```
+
+By default, the server runs on `0.0.0.0:8080`. Specify a different address:
+
+```bash
+log-socket -addr localhost:8080
 ```
 
-## Example Preview
+### Web Interface
+
+Open your browser and navigate to `http://localhost:8080`
+
+**Namespace Filtering:**
+- The namespace dropdown is automatically populated from `/api/namespaces`
+- Select one or more namespaces to filter (hold Ctrl/Cmd to multi-select)
+- Default is "All Namespaces" (shows everything)
+- Click "Reconnect" to apply the filter
+
+## API
 
-1. Start the server:
+### Logging Interface
 
-   ```bash
-   log-socket
-   ```
+The package provides two ways to log:
 
-   By default, the server runs on `0.0.0.0:8080`. You can specify a different address using the `-addr` flag:
+#### 1. Package-level functions (default namespace)
 
-   ```bash
-   log-socket -addr localhost:8080
-   ```
+```go
+logger.Trace("trace message")
+logger.Debug("debug message")
+logger.Info("info message")
+logger.Notice("notice message")
+logger.Warn("warning message")
+logger.Error("error message")
+logger.Panic("panic message")  // Logs and panics
+logger.Fatal("fatal message")  // Logs and exits
+```
+
+Each has formatted (`f`) and line (`ln`) variants:
+```go
+logger.Infof("User %s logged in", username)
+logger.Infoln("This adds a newline")
+```
 
-2. Open your browser and navigate to `http://localhost:8080`
+#### 2. Namespaced loggers
 
-   ![Log Socket Web Interface](browser/screenshot.png)
+```go
+apiLogger := logger.NewLogger("api")
+apiLogger.Info("Request received")
 
-## Logging Interface
+dbLogger := logger.NewLogger("database")  
+dbLogger.Warn("Slow query detected")
+```
+
+### Creating Clients with Namespace Filters
+
+```go
+// Listen to all namespaces
+client := logger.CreateClient()
+
+// Listen to specific namespace
+client := logger.CreateClient("api")
+
+// Listen to multiple namespaces
+client := logger.CreateClient("api", "database", "auth")
+```
 
-The package provides a comprehensive logging interface with the following methods:
+### WebSocket API
 
-- `Trace/Tracef/Traceln`: For trace-level logging
-- `Debug/Debugf/Debugln`: For debug-level logging
-- `Info/Infof/Infoln`: For info-level logging
-- `Notice/Noticef/Noticeln`: For notice-level logging
-- `Warn/Warnf/Warnln`: For warning-level logging
-- `Error/Errorf/Errorln`: For error-level logging
-- `Panic/Panicf/Panicln`: For panic-level logging
-- `Fatal/Fatalf/Fatalln`: For fatal-level logging
+#### Log Stream Endpoint
+
+**URL:** `ws://localhost:8080/ws`
+
+**Query Parameters:**
+- `namespaces` (optional): Comma-separated list of namespaces to filter
+
+**Examples:**
+```
+ws://localhost:8080/ws                     # All namespaces
+ws://localhost:8080/ws?namespaces=api      # Only "api" namespace
+ws://localhost:8080/ws?namespaces=api,database  # Multiple namespaces
+```
+
+**Message Format:**
+```json
+{
+  "timestamp": "2024-11-10T15:42:49.777298-05:00",
+  "output": "API request received",
+  "file": "main.go:42",
+  "level": "INFO",
+  "namespace": "api"
+}
+```
+
+#### Namespaces List Endpoint
+
+**URL:** `GET http://localhost:8080/api/namespaces`
+
+**Response:**
+```json
+{
+  "namespaces": ["default", "api", "database", "auth"]
+}
+```
 
 ## Web Interface Features
 
-- **Filtering**: Type in the search box to filter logs
-- **Auto-scroll**: Toggle auto-scrolling with the checkbox
+- **Namespace Dropdown**: Dynamically populated from `/api/namespaces`, multi-select support
+- **Text Search**: Filter logs by content, level, namespace, or source file
+- **Auto-scroll**: Toggle auto-scrolling with checkbox
 - **Download**: Save all logs as a JSON file
 - **Clear**: Remove all logs from the viewer
-- **Color Coding**: Different log levels are color-coded for easy identification
+- **Color Coding**: Different log levels are color-coded
+- **Reconnect**: Reconnect WebSocket with new namespace filter
+
+## Migration from v1
+
+### Import Path
+
+```go
+// v1
+import "github.com/taigrr/log-socket/log"
+
+// v2
+import "github.com/taigrr/log-socket/v2/log"
+```
+
+### CreateClient Changes
+
+```go
+// v1
+client := log.CreateClient()
+
+// v2 - specify namespace(s) or leave empty for all
+client := log.CreateClient()              // All namespaces
+client := log.CreateClient("api")         // Single namespace
+client := log.CreateClient("api", "db")   // Multiple namespaces
+```
+
+### New Logger Constructor
+
+```go
+// v2 only - create namespaced logger
+apiLogger := log.NewLogger("api")
+apiLogger.Info("Message in api namespace")
+```
 
 ## Dependencies
 
 - [gorilla/websocket](https://github.com/gorilla/websocket) for WebSocket support
 
 ## Notes
 
-The web interface is not meant to be used as-is.
-It functions perfectly well for some scenarios, but it is broken out into a different package intentionally, such that users can add their own as they see fit.
-It's mostly here to provide an example of how to consume the websocket data and display it.
+The web interface is provided as an example implementation. Users are encouraged to customize it for their specific needs. The WebSocket endpoint (`/ws`) can be consumed by any WebSocket client.
+
+## License
+
+See LICENSE file for details.