From a40d16dae0bb6256f40f2e04b9819b0c64432244 Mon Sep 17 00:00:00 2001
From: savinmax <savinmax@amazon.com>
Date: Thu, 11 Jun 2026 19:23:05 +0200
Subject: [PATCH] docs: update README with logging configuration section

Add documentation for the new logging config options (output and level),
including usage examples, field reference table, and updated project
structure listing the internal/logging package.
---
 README.md | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 288ee85..ec9fd2f 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,13 @@
 # WebSocket Relay Server
 
-A minimal Go WebSocket relay server that broadcasts every incoming message to all connected clients. Supports TLS, Prometheus metrics, and graceful shutdown.
+A minimal Go WebSocket relay server that broadcasts every incoming message to all connected clients. Supports TLS, Prometheus metrics, configurable logging, and graceful shutdown.
 
 ## Features
 
 - **Fan-out broadcasting** — every message is relayed to all connected clients
 - **TLS support** — optional `wss://` via cert/key PEM files
 - **Prometheus metrics** — connection counts, message totals, disconnections
+- **Configurable logging** — output to stdout, stderr, or file with level filtering
 - **Graceful shutdown** — clean exit on SIGINT/SIGTERM with client notification
 - **Zero dependencies at runtime** — single static binary
 
@@ -40,6 +41,10 @@ server:
 metrics:
   enabled: true
   port: 9090            # Prometheus metrics at :9090/metrics
+
+logging:
+  output: stderr        # stdout, stderr, or a file path
+  level: info           # debug, info, warn, error
 ```
 
 Override the config file path with `--config-file`:
@@ -48,6 +53,33 @@ Override the config file path with `--config-file`:
 ./websocket-relay --config-file=/etc/relay/config.yaml
 ```
 
+## Logging
+
+The `logging` section controls where and what the server logs:
+
+| Field | Values | Default | Description |
+|-------|--------|---------|-------------|
+| `output` | `stdout`, `stderr`, or a file path | `stderr` | Log output destination |
+| `level` | `debug`, `info`, `warn`, `error` | `info` | Minimum log level to output |
+
+**Examples:**
+
+```yaml
+# Log everything to a file
+logging:
+  output: /var/log/websocket-relay.log
+  level: debug
+
+# Quiet mode — only warnings and errors to stderr
+logging:
+  output: stderr
+  level: warn
+```
+
+Log messages are prefixed with the level: `[DEBUG]`, `[INFO]`, `[WARN]`, `[ERROR]`.
+
+File output uses append mode (`O_APPEND`) so logs are preserved across restarts and safe for external log rotation tools.
+
 ## Usage
 
 Connect any WebSocket client to the server:
@@ -110,10 +142,11 @@ websocket-relay/
 ├── internal/
 │   ├── config/config.go     # YAML config loader
 │   ├── hub/hub.go           # WebSocket hub, connection management, broadcast
+│   ├── logging/logging.go   # Log output setup and leveled logger
 │   └── metrics/metrics.go   # Prometheus metric definitions
 ├── example/index.html       # Browser P2P chat demo
 ├── config.yaml              # Runtime configuration
-├── config.example.yaml      # Example config with TLS enabled
+├── config.example.yaml      # Example config with TLS and logging
 └── Makefile                 # Build, test, release commands
 ```