152 lines
5.0 KiB
Markdown
152 lines
5.0 KiB
Markdown
# Go OTel Debugger
|
|
|
|
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
|
|
|
|
- **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.25+ (for local development)
|
|
- Docker (optional, for containerized deployment)
|
|
|
|
### Running Locally
|
|
|
|
1. Clone the repository:
|
|
```sh
|
|
git clone https://git.k6n.net/go-otel.git
|
|
cd go-otel
|
|
```
|
|
|
|
2. Run the server:
|
|
```sh
|
|
go run ./cmd/server
|
|
```
|
|
|
|
The server will start on ports 8080 (HTTP/WebSocket) and 4317 (gRPC).
|
|
|
|
### Running with Docker
|
|
|
|
1. Build the Docker image:
|
|
```sh
|
|
docker build -t go-otel .
|
|
```
|
|
|
|
2. Run the container:
|
|
```sh
|
|
docker run -p 8080:8080 -p 4317:4317 go-otel
|
|
```
|
|
|
|
### Kubernetes Deployment
|
|
|
|
Apply the included Kubernetes manifests:
|
|
```sh
|
|
kubectl apply -f k8s/
|
|
```
|
|
|
|
This deploys the application with a Service and Ingress for external access.
|
|
|
|
## API Endpoints
|
|
|
|
### OTLP HTTP Endpoints (Port 8080)
|
|
|
|
- `POST /v1/traces` - Receive OTLP traces
|
|
- `POST /v1/metrics` - Receive OTLP metrics
|
|
- `POST /v1/logs` - Receive OTLP logs
|
|
|
|
Supported Content-Types: `application/json`, `application/x-protobuf`
|
|
|
|
### OTLP gRPC Endpoints (Port 4317)
|
|
|
|
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
|
|
|
|
### Sending Telemetry Data
|
|
|
|
Send OTLP data to the appropriate endpoints. The data will be stored in history and broadcast to all connected WebSocket clients.
|
|
|
|
#### HTTP Example (JSON)
|
|
|
|
```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"}}]}]}]}]}'
|
|
```
|
|
|
|
#### 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.
|