From c3b62a3a953dea7a4f8f2b4f478952f632620c43 Mon Sep 17 00:00:00 2001 From: matst80 Date: Thu, 6 Nov 2025 18:57:28 +0100 Subject: [PATCH] update readme --- README.md | 187 ++++++++++++++++++----------------- internal/websocket/server.go | 2 +- 2 files changed, 97 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index 71ac08b..2775b5d 100644 --- a/README.md +++ b/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 -- Broadcasts received telemetry data over WebSocket connections -- Supports both JSON and Protocol Buffer formats -- Real-time debugging and visualization +- **OTLP Support**: Receives traces, metrics, and logs via both HTTP (JSON/Protobuf) and gRPC (Protobuf) protocols on standard OTLP ports. +- **Real-time Broadcasting**: Uses WebSocket connections to broadcast incoming telemetry data to all connected clients instantly. +- **Historical Data**: Maintains a configurable ring buffer of recent telemetry data, accessible via REST API endpoints. +- **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+ -- Docker (optional) +- Go 1.25+ (for local development) +- 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 -- **POST /v1/metrics**: Receive OTLP metrics -- **POST /v1/logs**: Receive OTLP logs +This deploys the application with a Service and Ingress for external access. -Supported Content-Types: -- `application/json` -- `application/x-protobuf` +## API Endpoints -### OTLP gRPC Endpoints +### OTLP HTTP Endpoints (Port 8080) -- **gRPC service**: `otlptracegrpc.TraceService.Export` -- **gRPC service**: `otlptracegrpc.MetricsService.Export` -- **gRPC service**: `otlptracegrpc.LogsService.Export` +- `POST /v1/traces` - Receive OTLP traces +- `POST /v1/metrics` - Receive OTLP metrics +- `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 -Open `http://localhost:8080` in your browser to see the real-time visualization. \ No newline at end of file +#### gRPC Example + +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. \ No newline at end of file diff --git a/internal/websocket/server.go b/internal/websocket/server.go index cbf266c..2c770c0 100644 --- a/internal/websocket/server.go +++ b/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) } }