Log Viewer for WaveCap-SDR

This skill provides tools to view, search, and analyze logs from the WaveCap-SDR server including API errors, SDR device messages, and debug output.

When to Use This Skill

Use this skill when:

• Troubleshooting API errors (500, 4xx responses)
• Investigating SDR device connection issues
• Debugging capture or channel problems
• Monitoring server health and status
• Reviewing recent API requests
• Checking for SoapySDR driver messages

Log Sources

Usage Instructions

Step 1: View Recent Error Logs

Check the debug error log for recent exceptions:

cat /tmp/wavecapsdr_error.log 2>/dev/null || echo "No error log found"

Or use the helper script:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/log-viewer/view_logs.py --errors

Step 2: Get Server Status

Check if the server is running and get process info:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/log-viewer/view_logs.py --status

Step 3: View API Request History

Get recent API requests from server logs (if available):

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/log-viewer/view_logs.py --requests

Step 4: Check SDR Device Logs

View SoapySDR-related messages:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/log-viewer/view_logs.py --sdr

Step 5: Test API Health

Verify API is responding and check health endpoint:

curl -s http://127.0.0.1:8087/api/v1/health | jq

Helper Script Reference

# View all available log info
python view_logs.py --all

# View only errors
python view_logs.py --errors

# View server status
python view_logs.py --status

# View recent API requests
python view_logs.py --requests

# View SDR device logs
python view_logs.py --sdr

# Specify custom port
python view_logs.py --port 8087 --all

# Filter by time (last N minutes)
python view_logs.py --errors --minutes 5

Common Log Patterns

Successful API Request

INFO:     127.0.0.1:12345 - "GET /api/v1/captures HTTP/1.1" 200 OK

Failed API Request

INFO:     127.0.0.1:12345 - "PATCH /api/v1/captures/c1 HTTP/1.1" 500 Internal Server Error

SDR Device Message

[SOAPY] Using stream format: CF32
[DEBUG] Device RTLSDR: Available antennas: ('RX',)

Error Traceback (in /tmp/wavecapsdr_error.log)

--- 2025-11-22 12:34:56.789 ---
[ERROR] update_capture failed: Device timeout
Traceback (most recent call last):
  ...

API Endpoints for Log Analysis

GET /api/v1/health

Returns server health status.

{
  "status": "healthy",
  "captures": 2,
  "channels": 2,
  "devices": 3
}

GET /api/v1/captures

Returns all captures with their current state and any error messages.

[
  {
    "id": "c1",
    "state": "running",
    "errorMessage": null
  }
]

GET /api/v1/channels/{chan_id}/metrics/extended

Returns detailed channel metrics including stream health.

Troubleshooting Common Issues

Issue: API Returns 500 Internal Server Error

Steps:

1. Check /tmp/wavecapsdr_error.log for traceback
2. Look for device-related errors in the log
3. Verify SDR device is connected: SoapySDRUtil --find
4. Check server stderr for SoapySDR errors

Issue: Capture Stuck in "starting" State

Steps:

1. Check for SDR driver errors in logs
2. Verify device isn't in use by another process
3. Look for timeout messages
4. Try restarting the capture

Issue: No Audio / Channel Not Working

Steps:

1. Check channel state via API
2. Look for demodulator errors in logs
3. Verify capture is running
4. Check signal metrics (RSSI, SNR)

Files in This Skill

• SKILL.md: This file - instructions for using the skill
• view_logs.py: Helper script for viewing and analyzing logs