Deepgram Debug Bundle

Overview
Prerequisites
Instructions
Output
Error Handling
Examples
Resources

Overview

Collect comprehensive debug information for Deepgram support tickets and troubleshooting. Bundles environment info, API connectivity tests, request logs, audio analysis, and reproduction scripts into a single archive.

Prerequisites

Deepgram API key configured
Access to application logs
Sample audio file that reproduces issue

Instructions

Step 1: Collect Environment Info

Gather system and SDK version information (Node.js, Python, OS, SDK versions).

Step 2: Test API Connectivity

Verify REST API and WebSocket endpoint reachability with curl against api.deepgram.com.

Step 3: Capture Request/Response

Use DeepgramDebugger class to log full request/response details with timing and error capture.

Step 4: Create Minimal Reproduction

Build a standalone script that reproduces the issue with the NASA podcast sample audio.

Step 5: Analyze Audio (if applicable)

Run ffprobe analysis on the audio file to verify format, encoding, and duration.

Step 6: Package Debug Bundle

Run collect-debug-bundle.sh to compile environment, connectivity, logs, and audio analysis into a .tar.gz archive.

Output

deepgram-debug-YYYYMMDD-HHMMSS.tar.gz containing:
- environment.txt - System and SDK versions
- connectivity.txt - API connectivity test results
- app-logs.txt - Recent application logs (sanitized)
- audio-analysis.txt - Audio file details (if provided)
- README.txt - Bundle description and issue template

Error Handling

Issue	Cause	Resolution
API connectivity fails	Invalid key or network	Verify `DEEPGRAM_API_KEY` and network access
Empty response	Silent or corrupt audio	Check audio format with `ffprobe`
SDK not found	Missing dependency	Run `npm list @deepgram/sdk` or `pip show deepgram-sdk`

Examples

Support Ticket Template

Include: issue summary, environment details, request IDs, steps to reproduce, expected vs actual behavior, and attach the debug bundle archive.

Quick Connectivity Test

set -euo pipefail
curl -s -o /dev/null -w "%{http_code}" \
  -X GET 'https://api.deepgram.com/v1/projects' \
  -H "Authorization: Token $DEEPGRAM_API_KEY"

See detailed implementation for advanced patterns.

deepgram-debug-bundle