go-otel/README.md

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.

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

Getting Started

Prerequisites

• Go 1.21+
• Docker (optional)

Running Locally

1. Clone the repository:

   git clone https://git.tornberg.me/go-otel.git
   cd go-otel
   

2. Run the server:

   go run ./cmd/server
   

The server will be running on port 8080.

Running with Docker

1. Build the Docker image:

   docker build -t go-otel .
   

2. Run the Docker container:

   docker run -p 8080:8080 go-otel
   

API

OTLP HTTP Endpoints

• 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

• gRPC service: otlptracegrpc.TraceService.Export
• gRPC service: otlptracegrpc.MetricsService.Export
• gRPC service: otlptracegrpc.LogsService.Export

gRPC server runs on port 4317 (standard OTLP gRPC port).

WebSocket

• GET /ws: Connect to receive real-time telemetry data

Usage

Send OTLP data to the appropriate endpoints. The data will be broadcast to all connected WebSocket clients for visualization.

Open http://localhost:8080 in your browser to access the web-based visualizer.

HTTP Examples

Example with curl (JSON):

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:

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:

   go run ./cmd/server
   

2. In another terminal, run the test client:

   cd test-client && go run .
   

Or use the provided test script:

./test.sh

The test client will send sample traces via both HTTP and gRPC protocols.

Manual Testing

HTTP Testing

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.