oteldebug

How to Use oteldebug

oteldebug is a tool for debugging OpenTelemetry data by capturing and displaying traces, logs, and metrics in real-time. Follow the steps below to get started.

Step 1: Generate a Debug Token

1. Navigate to the home page
2. Click the "Generate Token" button
3. Copy the generated token (valid for 5 minutes)

Step 2: Add the Token to Your Telemetry Data

Add the oteldebug attribute with your token value to your telemetry data:

• For Traces: Add as a span attribute
• For Logs: Add as a log record attribute
• For Metrics: Add as a resource attribute

Step 3: Send Telemetry Data

Send your telemetry data to one of these endpoints:

• HTTP: http://localhost:4318/v1/traces | logs | metrics
• gRPC: localhost:4317

Example: Using telemetrygen

Here's how to send test traces using telemetrygen:

telemetrygen traces \
  --otlp-endpoint localhost:4317 \
  --otlp-insecure \
  --traces 10 \
  --duration 10s \
  --rate 1 \
  --status-code Ok \
  --span-duration 100ms \
  --telemetry-attributes 'oteldebug="YOUR_TOKEN_HERE"'

Replace YOUR_TOKEN_HERE with the token you generated in Step 1.

Step 4: View Your Data

Once you've sent telemetry data, it will appear automatically on the home page under the corresponding tab (Traces, Logs, or Metrics). The page updates every 5 seconds.

Architecture Overview

The system works as follows:

1. Your application sends OTLP telemetry to the OpenTelemetry Collector
2. The collector filters data containing the oteldebug attribute
3. Filtered data is published to Kafka topics
4. The backend API consumes Kafka messages and stores them in SQLite
5. The web UI fetches and displays your telemetry data in real-time

Endpoints

• OTLP gRPC: localhost:4317
• OTLP HTTP: localhost:4318
• API: localhost:8080
• Web UI: localhost:3000
• Kafka UI: localhost:8900