update readme

README.md

@@ -1,20 +1,39 @@
 # Go OTel Debugger
 
-This is a debug OpenTelemetry receiver that accepts traces, metrics, and logs via OTLP HTTP protocol and broadcasts them over WebSocket connections for real-time visualization.
+A debug receiver for OpenTelemetry telemetry data (traces, metrics, and logs) that provides real-time visualization and historical data access. It accepts OTLP data via HTTP and gRPC protocols, stores a configurable history of received telemetry, and broadcasts updates to connected WebSocket clients for live debugging.
 
 ## Features
 
-- Receives OTLP traces, metrics, and logs over HTTP
+- **OTLP Support**: Receives traces, metrics, and logs via both HTTP (JSON/Protobuf) and gRPC (Protobuf) protocols on standard OTLP ports.
-- Broadcasts received telemetry data over WebSocket connections
+- **Real-time Broadcasting**: Uses WebSocket connections to broadcast incoming telemetry data to all connected clients instantly.
-- Supports both JSON and Protocol Buffer formats
+- **Historical Data**: Maintains a configurable ring buffer of recent telemetry data, accessible via REST API endpoints.
-- Real-time debugging and visualization
+- **Web Interface**: Includes a built-in HTML interface for visualizing telemetry data in real-time with counters and clear buttons.
+- **Docker Support**: Containerized for easy deployment.
+- **Kubernetes Ready**: Includes deployment manifests for Kubernetes clusters.
+
+## Architecture
+
+The application consists of several key components:
+
+1. **HTTP/gRPC Servers**: Handle incoming OTLP requests on ports 8080 (HTTP) and 4317 (gRPC).
+2. **Collector**: Processes and stores telemetry data in a ring buffer for history. Implements OpenTelemetry consumer interfaces.
+3. **WebSocket Server**: Manages client connections and broadcasts new telemetry data as JSON messages.
+4. **Web Interface**: Static HTML page served on the root path that connects to the WebSocket for real-time updates.
+5. **History API**: REST endpoints to retrieve stored telemetry data by type or all combined.
+
+Data flow:
+```
+OTLP Client → HTTP/gRPC Server → Collector → WebSocket Broadcast → Connected Clients
+                                      ↓
+                                 History Storage → REST API → Clients
+```
 
 ## Getting Started
 
 ### Prerequisites
 
-- Go 1.21+
+- Go 1.25+ (for local development)
-- Docker (optional)
+- Docker (optional, for containerized deployment)
 
 ### Running Locally
 
@@ -29,7 +48,7 @@ This is a debug OpenTelemetry receiver that accepts traces, metrics, and logs vi
    go run ./cmd/server
    ```
 
-The server will be running on port 8080.
+The server will start on ports 8080 (HTTP/WebSocket) and 4317 (gRPC).
 
 ### Running with Docker
 
@@ -38,109 +57,95 @@ The server will be running on port 8080.
    docker build -t go-otel .
    ```
 
-2. Run the Docker container:
+2. Run the container:
    ```sh
-   docker run -p 8080:8080 go-otel
+   docker run -p 8080:8080 -p 4317:4317 go-otel
    ```
 
-## API
+### Kubernetes Deployment
 
-### OTLP HTTP Endpoints
+Apply the included Kubernetes manifests:
+```sh
+kubectl apply -f k8s/
+```
 
-- **POST /v1/traces**: Receive OTLP traces
+This deploys the application with a Service and Ingress for external access.
-- **POST /v1/metrics**: Receive OTLP metrics  
-- **POST /v1/logs**: Receive OTLP logs
 
-Supported Content-Types:
+## API Endpoints
-- `application/json`
-- `application/x-protobuf`
 
-### OTLP gRPC Endpoints
+### OTLP HTTP Endpoints (Port 8080)
 
-- **gRPC service**: `otlptracegrpc.TraceService.Export`
+- `POST /v1/traces` - Receive OTLP traces
-- **gRPC service**: `otlptracegrpc.MetricsService.Export`
+- `POST /v1/metrics` - Receive OTLP metrics  
-- **gRPC service**: `otlptracegrpc.LogsService.Export`
+- `POST /v1/logs` - Receive OTLP logs
 
-gRPC server runs on port 4317 (standard OTLP gRPC port).
+Supported Content-Types: `application/json`, `application/x-protobuf`
 
-### WebSocket
+### OTLP gRPC Endpoints (Port 4317)
 
-- **GET /ws**: Connect to receive real-time telemetry data
+gRPC services for traces, metrics, and logs using standard OTLP protobuf definitions.
+
+### WebSocket Endpoint (Port 8080)
+
+- `GET /ws` - WebSocket connection for real-time telemetry streaming
+
+### History API Endpoints (Port 8080)
+
+- `GET /api/history` - Retrieve all historical telemetry data
+- `GET /api/history/traces` - Retrieve only trace history
+- `GET /api/history/metrics` - Retrieve only metrics history
+- `GET /api/history/logs` - Retrieve only logs history
+
+### Web Interface
+
+- `GET /` - Serves the HTML visualization interface
 
 ## Usage
 
-Send OTLP data to the appropriate endpoints. The data will be broadcast to all connected WebSocket clients for visualization.
+### Sending Telemetry Data
 
-Open `http://localhost:8080` in your browser to access the web-based visualizer.
+Send OTLP data to the appropriate endpoints. The data will be stored in history and broadcast to all connected WebSocket clients.
 
-### HTTP Examples
+#### HTTP Example (JSON)
 
-Example with curl (JSON):
-```sh
-curl -X POST http://localhost:8080/v1/traces \
-  -H "Content-Type: application/json" \
-  -d @trace-data.json
-```
-
-### gRPC Examples
-
-Use OTLP gRPC clients or libraries to send data to `localhost:4317`.
-
-### WebSocket
-
-Connect to WebSocket to receive the data:
-```javascript
-const ws = new WebSocket('ws://localhost:8080/ws');
-ws.onmessage = (event) => {
-  console.log('Received:', JSON.parse(event.data));
-};
-```
-
-## Web Interface
-
-The web interface provides real-time visualization of:
-- Traces
-- Metrics  
-- Logs
-
-Features:
-- Live data streaming via WebSocket
-- Separate sections for each telemetry type
-- Message counters
-- Clear buttons for each section
-- Connection status indicator
-
-## Testing
-
-A test client is included to verify that the receiver works correctly.
-
-### Run the Test
-
-1. Start the receiver:
-   ```sh
-   go run ./cmd/server
-   ```
-
-2. In another terminal, run the test client:
-   ```sh
-   cd test-client && go run .
-   ```
-
-Or use the provided test script:
-```sh
-./test.sh
-```
-
-The test client will send sample traces via both HTTP and gRPC protocols.
-
-### Manual Testing
-
-#### HTTP Testing
 ```sh
 curl -X POST http://localhost:8080/v1/traces \
   -H "Content-Type: application/json" \
   -d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"test-service"}}]},"scopeSpans":[{"scope":{"name":"test-scope"},"spans":[{"traceId":"0102030405060708090a0b0c0d0e0f10","spanId":"0102030405060708","name":"test-span","startTimeUnixNano":"1640995200000000000","endTimeUnixNano":"1640995260000000000","attributes":[{"key":"test.key","value":{"stringValue":"test-value"}}]}]}]}]}'
 ```
 
-#### Web Interface
+#### gRPC Example
-Open `http://localhost:8080` in your browser to see the real-time visualization.
+
+Use any OTLP gRPC client library to send data to `localhost:4317`.
+
+### Real-time Visualization
+
+1. Open `http://localhost:8080` in your browser
+2. The interface will automatically connect via WebSocket
+3. Send telemetry data to see it appear in real-time
+4. Use the "Clear" buttons to reset individual data sections
+5. View message counters for each telemetry type
+
+### Accessing Historical Data
+
+Use the history API endpoints to retrieve previously received data:
+
+```sh
+curl http://localhost:8080/api/history/traces
+```
+
+This returns JSON arrays of historical entries with timestamps.
+
+## Configuration
+
+Currently, the history buffer size is hardcoded to 100 entries. This can be made configurable in future versions.
+
+## Development
+
+To modify the application:
+
+1. Edit source files in `cmd/server/` and `internal/`
+2. Run locally with `go run ./cmd/server`
+3. For UI changes, edit `index.html` directly
+
+The application uses standard Go modules and OpenTelemetry collector libraries for data processing.

internal/websocket/server.go

@@ -149,6 +149,6 @@ func (s *Server) HandleMessage(ws *websocket.Conn, msg []byte) {
 
 func (s *Server) SendPong(ws *websocket.Conn) {
 	if err := ws.WriteMessage(websocket.PongMessage, nil); err != nil {
-		log.Printf("error sending pong", err)
+		log.Printf("error sending pong: %v", err)
 	}
 }