Groq Debug Bundle Skill

Groq Debug Bundle

Current State

!node --version 2>/dev/null || echo 'N/A' !python3 --version 2>/dev/null || echo 'N/A' !npm list groq-sdk 2>/dev/null | grep groq-sdk || echo 'groq-sdk not installed'

Overview

Collect all diagnostic information needed to resolve Groq API issues. Produces a redacted support bundle with environment info, SDK version, connectivity test results, and rate limit status.

Prerequisites

GROQ_API_KEY set in environment
curl and jq available
Access to application logs

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
set -euo pipefail

BUNDLE_DIR="groq-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"
echo "Collecting Groq debug bundle..."

# === Environment ===
cat > "$BUNDLE_DIR/environment.txt" <<ENVEOF
=== Groq Debug Bundle ===
Generated: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
Hostname: $(hostname)
OS: $(uname -sr)
Node.js: $(node --version 2>/dev/null || echo 'not installed')
Python: $(python3 --version 2>/dev/null || echo 'not installed')
npm groq-sdk: $(npm list groq-sdk 2>/dev/null | grep groq-sdk || echo 'not installed')
pip groq: $(pip show groq 2>/dev/null | grep Version || echo 'not installed')
GROQ_API_KEY: ${GROQ_API_KEY:+SET (${#GROQ_API_KEY} chars, prefix: ${GROQ_API_KEY:0:4}...)}${GROQ_API_KEY:-NOT SET}
ENVEOF

Step 2: API Connectivity Test

# Test API endpoint and capture headers
echo "--- API Connectivity ---" >> "$BUNDLE_DIR/connectivity.txt"

# Models endpoint (lightweight, confirms auth)
curl -s -w "\nHTTP Status: %{http_code}\nTime: %{time_total}s\n" \
  https://api.groq.com/openai/v1/models \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  | jq '.data | length' >> "$BUNDLE_DIR/connectivity.txt" 2>&1

echo "Models available: $(curl -s https://api.groq.com/openai/v1/models \
  -H "Authorization: Bearer $GROQ_API_KEY" | jq -r '.data[].id' | wc -l)" \
  >> "$BUNDLE_DIR/connectivity.txt"

Step 3: Rate Limit Status

# Make a minimal request and capture rate limit headers
echo "--- Rate Limit Status ---" >> "$BUNDLE_DIR/rate-limits.txt"

curl -si https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"llama-3.1-8b-instant","messages":[{"role":"user","content":"ping"}],"max_tokens":1}' \
  2>/dev/null | grep -iE "^(x-ratelimit|retry-after|x-request-id)" \
  >> "$BUNDLE_DIR/rate-limits.txt"

Step 4: Latency Benchmark

# Quick latency test across models
echo "--- Latency Benchmark ---" >> "$BUNDLE_DIR/latency.txt"

for model in "llama-3.1-8b-instant" "llama-3.3-70b-versatile"; do
  latency=$(curl -s -w "%{time_total}" -o /dev/null \
    https://api.groq.com/openai/v1/chat/completions \
    -H "Authorization: Bearer $GROQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"model\":\"$model\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}],\"max_tokens\":5}" \
    2>/dev/null)
  echo "$model: ${latency}s" >> "$BUNDLE_DIR/latency.txt"
done

Step 5: Application Log Extraction

# Capture recent Groq-related errors from application logs (redacted)
echo "--- Application Logs (redacted) ---" >> "$BUNDLE_DIR/app-logs.txt"

# Node.js logs
if [ -d "logs" ]; then
  grep -i "groq\|rate.limit\|429\|api.error" logs/*.log 2>/dev/null | \
    tail -50 | \
    sed 's/gsk_[a-zA-Z0-9]*/gsk_***REDACTED***/g' \
    >> "$BUNDLE_DIR/app-logs.txt"
fi

# Config (redacted)
echo "--- Config (redacted) ---" >> "$BUNDLE_DIR/config-redacted.txt"
if [ -f ".env" ]; then
  sed 's/=.*/=***REDACTED***/' .env >> "$BUNDLE_DIR/config-redacted.txt"
fi

Step 6: Package Bundle

# Create tarball
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo "Review before sharing -- ensure no secrets are included."

Programmatic Debug Check (TypeScript)

import Groq from "groq-sdk";

async function groqDiagnostic() {
  const groq = new Groq();
  const report: Record<string, any> = {};

  // Test auth
  try {
    const models = await groq.models.list();
    report.auth = "OK";
    report.modelsAvailable = models.data.map((m) => m.id);
  } catch (err) {
    report.auth = `FAILED: ${(err as Error).message}`;
    return report;
  }

  // Test completion
  try {
    const start = performance.now();
    const completion = await groq.chat.completions.create({
      model: "llama-3.1-8b-instant",
      messages: [{ role: "user", content: "Reply: OK" }],
      max_tokens: 5,
      temperature: 0,
    });
    report.completion = "OK";
    report.latencyMs = Math.round(performance.now() - start);
    report.model = completion.model;
    report.usage = completion.usage;
  } catch (err: any) {
    report.completion = `FAILED: ${err.status} ${err.message}`;
  }

  return report;
}

groqDiagnostic().then((r) => console.log(JSON.stringify(r, null, 2)));

Bundle Contents

| File | Purpose | Sensitive? | |------|---------|-----------| | environment.txt | Node/Python versions, SDK version | Key prefix only | | connectivity.txt | API reachability, model count | No | | rate-limits.txt | Current rate limit headers | No | | latency.txt | Response times per model | No | | app-logs.txt | Recent error logs (redacted) | Redacted | | config-redacted.txt | Config keys only (values masked) | Redacted |

ALWAYS Redact Before Sharing

API keys (anything starting with gsk_)
Bearer tokens
PII (emails, names, IDs)
Internal hostnames and IPs

Resources

Next Steps

For rate limit issues, see groq-rate-limits.

Agent Skills: Groq Debug Bundle

Install this agent skill to your local

Skill Files