Deepgram Debug Bundle

Overview

Collect comprehensive debug information for Deepgram support tickets and troubleshooting.

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.

Step 2: Capture Request/Response

Log full API request and response details.

Step 3: Test with Minimal Example

Create a standalone reproduction script.

Step 4: Package Debug Bundle

Compile all information for support.

Debug Bundle Contents

1. Environment Information

#!/bin/bash
# debug-env.sh

echo "=== Environment Info ===" > debug-bundle.txt
echo "Date: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> debug-bundle.txt
echo "OS: $(uname -a)" >> debug-bundle.txt
echo "Node: $(node --version 2>/dev/null || echo 'N/A')" >> debug-bundle.txt
echo "Python: $(python3 --version 2>/dev/null || echo 'N/A')" >> debug-bundle.txt
echo "" >> debug-bundle.txt

echo "=== SDK Versions ===" >> debug-bundle.txt
npm list @deepgram/sdk 2>/dev/null >> debug-bundle.txt
pip show deepgram-sdk 2>/dev/null >> debug-bundle.txt

2. API Connectivity Test

#!/bin/bash
# debug-connectivity.sh

echo "=== API Connectivity ===" >> debug-bundle.txt

# Test REST API
echo "REST API:" >> debug-bundle.txt
curl -s -o /dev/null -w "%{http_code}" \
  -X GET 'https://api.deepgram.com/v1/projects' \
  -H "Authorization: Token $DEEPGRAM_API_KEY" >> debug-bundle.txt
echo "" >> debug-bundle.txt

# Test WebSocket
echo "WebSocket endpoint reachable:" >> debug-bundle.txt
curl -s -o /dev/null -w "%{http_code}" \
  -X GET 'https://api.deepgram.com/v1/listen' \
  -H "Authorization: Token $DEEPGRAM_API_KEY" >> debug-bundle.txt

3. Request Logger

// debug-logger.ts
import { createClient } from '@deepgram/sdk';
import { writeFileSync, appendFileSync } from 'fs';

interface DebugLog {
  timestamp: string;
  requestId?: string;
  operation: string;
  request: {
    url: string;
    options: Record<string, unknown>;
    audioSize?: number;
  };
  response?: {
    status: number;
    body: unknown;
    duration: number;
  };
  error?: {
    code: string;
    message: string;
    stack?: string;
  };
}

export class DeepgramDebugger {
  private logs: DebugLog[] = [];
  private client;

  constructor(apiKey: string) {
    this.client = createClient(apiKey);
  }

  async transcribeWithDebug(
    audioUrl: string,
    options: Record<string, unknown> = {}
  ) {
    const log: DebugLog = {
      timestamp: new Date().toISOString(),
      operation: 'transcribeUrl',
      request: {
        url: audioUrl,
        options,
      },
    };

    const startTime = Date.now();

    try {
      const { result, error } = await this.client.listen.prerecorded.transcribeUrl(
        { url: audioUrl },
        { model: 'nova-2', ...options }
      );

      log.response = {
        status: error ? 400 : 200,
        body: result || error,
        duration: Date.now() - startTime,
      };

      if (result?.metadata?.request_id) {
        log.requestId = result.metadata.request_id;
      }

      if (error) {
        log.error = {
          code: error.code || 'UNKNOWN',
          message: error.message || 'Unknown error',
        };
      }
    } catch (err) {
      log.error = {
        code: 'EXCEPTION',
        message: err instanceof Error ? err.message : String(err),
        stack: err instanceof Error ? err.stack : undefined,
      };
      log.response = {
        status: 0,
        body: null,
        duration: Date.now() - startTime,
      };
    }

    this.logs.push(log);
    return log;
  }

  exportLogs(filePath: string = './deepgram-debug.json') {
    writeFileSync(filePath, JSON.stringify(this.logs, null, 2));
    console.log(`Debug logs exported to ${filePath}`);
  }

  exportForSupport() {
    const sanitized = this.logs.map(log => ({
      ...log,
      // Remove any sensitive data
      request: {
        ...log.request,
        // Mask API key if accidentally logged
      },
    }));

    return {
      timestamp: new Date().toISOString(),
      logs: sanitized,
      summary: {
        totalRequests: this.logs.length,
        failedRequests: this.logs.filter(l => l.error).length,
        averageDuration: this.logs.reduce((sum, l) =>
          sum + (l.response?.duration || 0), 0) / this.logs.length,
      },
    };
  }
}

4. Minimal Reproduction Script

// debug-repro.ts
/**
 * Minimal reproduction script for Deepgram issue
 *
 * Issue: [DESCRIBE ISSUE HERE]
 * Expected: [EXPECTED BEHAVIOR]
 * Actual: [ACTUAL BEHAVIOR]
 *
 * To run:
 * DEEPGRAM_API_KEY=xxx npx ts-node debug-repro.ts
 */

import { createClient } from '@deepgram/sdk';

async function reproduce() {
  console.log('Starting reproduction...');
  console.log('SDK Version:', require('@deepgram/sdk/package.json').version);
  console.log('Node Version:', process.version);

  const client = createClient(process.env.DEEPGRAM_API_KEY!);

  try {
    // Minimal code to reproduce issue
    const { result, error } = await client.listen.prerecorded.transcribeUrl(
      { url: 'https://static.deepgram.com/examples/nasa-podcast.wav' },
      { model: 'nova-2' }
    );

    if (error) {
      console.error('Error:', JSON.stringify(error, null, 2));
    } else {
      console.log('Success:', result.metadata.request_id);
    }
  } catch (err) {
    console.error('Exception:', err);
  }
}

reproduce();

5. Audio Analysis

#!/bin/bash
# debug-audio.sh

AUDIO_FILE=$1

echo "=== Audio Analysis ===" >> debug-bundle.txt
echo "File: $AUDIO_FILE" >> debug-bundle.txt
echo "Size: $(stat -f%z "$AUDIO_FILE" 2>/dev/null || stat -c%s "$AUDIO_FILE")" >> debug-bundle.txt

# FFprobe analysis (if available)
if command -v ffprobe &> /dev/null; then
  echo "FFprobe output:" >> debug-bundle.txt
  ffprobe -v quiet -print_format json -show_format -show_streams "$AUDIO_FILE" >> debug-bundle.txt
fi

Complete Debug Bundle Script

#!/bin/bash
# collect-debug-bundle.sh

BUNDLE_DIR="deepgram-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "Collecting Deepgram debug bundle..."

# 1. Environment info
./debug-env.sh > "$BUNDLE_DIR/environment.txt"

# 2. Connectivity test
./debug-connectivity.sh > "$BUNDLE_DIR/connectivity.txt"

# 3. Recent logs (sanitized)
grep -i deepgram /var/log/app/*.log 2>/dev/null | tail -100 > "$BUNDLE_DIR/app-logs.txt"

# 4. Audio file info (if provided)
if [ -n "$1" ]; then
  ./debug-audio.sh "$1" > "$BUNDLE_DIR/audio-analysis.txt"
fi

# 5. Package info
cat > "$BUNDLE_DIR/README.txt" << EOF
Deepgram Debug Bundle
Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)

Contents:
- environment.txt: System and SDK versions
- connectivity.txt: API connectivity tests
- app-logs.txt: Recent application logs
- audio-analysis.txt: Audio file details (if provided)

Issue Description:
[ADD YOUR ISSUE DESCRIPTION HERE]

Request IDs:
[ADD RELEVANT REQUEST IDS HERE]
EOF

# Create archive
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Debug bundle created: $BUNDLE_DIR.tar.gz"

Support Ticket Template

## Issue Summary
[Brief description of the issue]

## Environment
- SDK: @deepgram/sdk v[VERSION]
- Node.js: v[VERSION]
- OS: [OS and version]

## Request ID(s)
- [request_id from response metadata]

## Steps to Reproduce
1. [Step 1]
2. [Step 2]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Debug Bundle
[Attach debug-bundle.tar.gz]

## Audio Sample
[If applicable, attach sample audio or provide URL]

Resources

Next Steps

Proceed to deepgram-rate-limits for rate limiting implementation.

deepgram-debug-bundle