Add OTLP debug sink for telemetry debugging

[aygp-dr]

Feature Request: OTLP Debug Sink

Problem

When debugging OTLP telemetry issues, it's useful to have a simple sink that captures raw OTLP HTTP requests without requiring a full Prometheus/OTLP collector setup. This helps diagnose:

• Payload format issues
• Authentication headers
• Request frequency
• Metric structure

Solution

Add a Makefile target that starts a simple netcat listener on port 14318 (OTLP HTTP port) and logs all incoming requests.

Implementation

# Simple OTLP debug sink using netcat
nc -l 14318  < /dev/null |  tee otlp-debug-sink-$(date +%Y%m%d-%H%M%S).log

Benefits

• Zero dependencies (just netcat)
• Captures raw HTTP requests
• Timestamped log files
• Quick debugging without full stack
• Useful for test matrix validation

Usage

# Terminal 1: Start the debug sink
make otlp-debug-sink

# Terminal 2: Configure Claude Code
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:14318
export OTEL_METRICS_EXPORTER=otlp
claude --enable-telemetry

Related

• Part of the pedagogical telemetry approach
• Complements test_matrix.py for protocol debugging
• Helps validate OTLP contract specifications

[aygp-dr]

@claude implement this feature based on the issue description

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[aygp-dr]

@claude implement this feature based on the issue description

[claude]

Claude finished @aygp-dr's task —— View job

---

OTLP Debug Sink Feature Analysis

Task List

• Read repository setup instructions (CLAUDE.org)
• Analyze existing Makefile structure
• Implement otlp-debug-sink target in Makefile (Already implemented!)
• Validate Makefile syntax (syntax is correct)
• Commit changes to branch (No changes needed)
• Provide PR creation link (Feature already exists)

Summary

The OTLP debug sink feature has already been implemented in the Makefile! The current implementation on lines 78-87 provides exactly what was requested in the issue:

✅ Feature Implementation

• Target: otlp-debug-sink
• Port: 14318 (standard OTLP HTTP port)
• Command: nc -l 14318 | tee "otlp-debug-sink-$(date +%Y%m%d-%H%M%S).log"
• Zero dependencies: Uses only netcat (standard on most systems)
• Timestamped logs: Automatic file naming with YYYYMMDD-HHMMSS format

✅ User Experience

• Clear startup instructions displayed
• Claude Code configuration examples provided
• Help text included in make help output
• Proper .PHONY target declaration for Makefile best practices

✅ Additional Features

The Makefile also includes two enhanced variants:

• otlp-interceptor: Captures AND forwards requests to pi.lan:4318
• otlp-interceptor-verbose: Adds real-time analysis with grep filtering

Usage

# Terminal 1: Start the debug sink
make otlp-debug-sink

# Terminal 2: Configure Claude Code
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:14318
export OTEL_METRICS_EXPORTER=otlp
claude --enable-telemetry

The feature is ready to use immediately - no additional implementation required!

---

[claude]

Claude finished @aygp-dr's task —— View job

---

OTLP Debug Sink Feature Analysis Complete

Todo List:

• Read repository setup instructions (CLAUDE.md)
• Examine existing Makefile structure
• Add otlp-debug-sink target to Makefile (Already implemented!)
• Test the implementation (Cannot test without Bash permissions)
• Commit changes (No changes needed)

Summary:

The OTLP debug sink feature already exists in the Makefile! Upon examining the codebase, I found that the exact feature requested in issue #9 has already been implemented:

Current Implementation (Makefile:78-87):

otlp-debug-sink: ## Capture raw OTLP HTTP requests without forwarding
	@echo "Starting OTLP debug sink on port 14318..."
	@echo "This captures raw OTLP HTTP requests for debugging"
	@echo "Configure Claude Code with:"
	@echo "  export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:14318"
	@echo "  export OTEL_METRICS_EXPORTER=otlp"
	@echo ""
	@echo "Press Ctrl+C to stop"
	@echo "Logging to: otlp-debug-sink-$$(date +%Y%m%d-%H%M%S).log"
	@nc -l 14318 | tee "otlp-debug-sink-$$(date +%Y%m%d-%H%M%S).log"

What's included:
✅ Netcat listener on port 14318 (OTLP HTTP port)
✅ Timestamped log files (otlp-debug-sink-YYYYMMDD-HHMMSS.log)
✅ Zero dependencies (just netcat)
✅ User instructions for Claude Code configuration
✅ Help documentation
✅ Clean output with progress indicators

Bonus features also implemented:

• otlp-interceptor: Captures AND forwards to pi.lan:4318
• otlp-interceptor-verbose: Adds real-time analysis

The feature is ready to use with:

make otlp-debug-sink

Issue Status: This feature request appears to be already complete. The implementation matches the specification exactly.

---