Brightdata debug bundle

Bright Data Debug Bundle

Overview

Collect all diagnostic information needed for Bright Data support tickets: proxy connectivity, zone status, response headers, and error logs.

Prerequisites

• Bright Data zone credentials configured
• curl available
• Permission to collect environment info

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
# brightdata-debug-bundle.sh
set -euo pipefail

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

echo "=== Bright Data Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u)" | tee -a "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

Step 2: Collect Environment and Connectivity

# Runtime versions
echo "--- Runtime ---" >> "$BUNDLE_DIR/summary.txt"
node --version >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "Node.js: not found" >> "$BUNDLE_DIR/summary.txt"
python3 --version >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "Python: not found" >> "$BUNDLE_DIR/summary.txt"

# Credential check (presence only, never log values)
echo "--- Credentials ---" >> "$BUNDLE_DIR/summary.txt"
echo "BRIGHTDATA_CUSTOMER_ID: ${BRIGHTDATA_CUSTOMER_ID:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "BRIGHTDATA_ZONE: ${BRIGHTDATA_ZONE:-[NOT SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "BRIGHTDATA_ZONE_PASSWORD: ${BRIGHTDATA_ZONE_PASSWORD:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "BRIGHTDATA_API_TOKEN: ${BRIGHTDATA_API_TOKEN:+[SET]}" >> "$BUNDLE_DIR/summary.txt"

# SSL cert check
echo "--- SSL Certificate ---" >> "$BUNDLE_DIR/summary.txt"
if [ -f "./brd-ca.crt" ]; then
  openssl x509 -in ./brd-ca.crt -noout -subject -enddate >> "$BUNDLE_DIR/summary.txt" 2>&1
else
  echo "brd-ca.crt: NOT FOUND" >> "$BUNDLE_DIR/summary.txt"
fi

Step 3: Test Proxy Connectivity with Verbose Headers

# Proxy connectivity test with full response headers
echo "--- Proxy Test ---" >> "$BUNDLE_DIR/summary.txt"
PROXY_USER="brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}"
curl -x "http://${PROXY_USER}:${BRIGHTDATA_ZONE_PASSWORD}@brd.superproxy.io:33335" \
  -s -D "$BUNDLE_DIR/proxy-headers.txt" \
  -o "$BUNDLE_DIR/proxy-response.txt" \
  -w "HTTP %{http_code} in %{time_total}s\n" \
  https://lumtest.com/myip.json 2>> "$BUNDLE_DIR/summary.txt" || echo "Proxy FAILED" >> "$BUNDLE_DIR/summary.txt"

# Extract X-Luminati headers (error details)
grep -i "x-luminati\|x-brd" "$BUNDLE_DIR/proxy-headers.txt" >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || true

# Direct connectivity test (bypasses proxy)
echo "--- Direct Connectivity ---" >> "$BUNDLE_DIR/summary.txt"
curl -s -o /dev/null -w "brightdata.com: HTTP %{http_code}\n" https://brightdata.com >> "$BUNDLE_DIR/summary.txt"
curl -s -o /dev/null -w "status page: HTTP %{http_code}\n"  >> "$BUNDLE_DIR/summary.txt"

# Port check
echo "--- Port Connectivity ---" >> "$BUNDLE_DIR/summary.txt"
nc -zv brd.superproxy.io 33335 >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "Port 33335: BLOCKED" >> "$BUNDLE_DIR/summary.txt"
nc -zv brd.superproxy.io 9222 >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "Port 9222: BLOCKED" >> "$BUNDLE_DIR/summary.txt"

Step 4: Check Zone Status via API

# Zone status (requires API token)
if [ -n "${BRIGHTDATA_API_TOKEN:-}" ]; then
  echo "--- Zone Status ---" >> "$BUNDLE_DIR/summary.txt"
  curl -s -H "Authorization: Bearer ${BRIGHTDATA_API_TOKEN}" \
    "https://api.brightdata.com/zone/get_active_zones" \
    | python3 -m json.tool >> "$BUNDLE_DIR/zone-status.json" 2>/dev/null || true
fi

Step 5: Package and Report

# Collect recent error logs (redacted)
if [ -d "logs" ]; then
  grep -i "brightdata\|proxy\|502\|407\|luminati" logs/*.log 2>/dev/null \
    | tail -100 | sed 's/password=[^ ]*/password=***REDACTED***/g' \
    >> "$BUNDLE_DIR/error-logs.txt"
fi

# Package bundle
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo ""
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo "Contents:"
ls -la "$BUNDLE_DIR/"
echo ""
echo "REVIEW FOR SENSITIVE DATA BEFORE SHARING"

Output

• summary.txt — credentials check, connectivity results, error headers
• proxy-headers.txt — full proxy response headers with X-Luminati diagnostics
• proxy-response.txt — proxy test response body
• zone-status.json — zone configuration and status
• error-logs.txt — recent errors (passwords redacted)

Sensitive Data Checklist

ALWAYS REDACT before sharing:

• API tokens and zone passwords
• Customer IDs
• Target URLs (if confidential)

Safe to include:

• Error codes and X-Luminati headers
• Response timing
• Runtime versions
• Port connectivity results

Resources

• Bright Data Support Portal
• Status Page
• Troubleshooting Guide

Next Steps

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