algolia-debug-bundle | algolia-pack

Stats

Actions

Tags

algolia-debug-bundle | algolia-pack

Algolia Debug Bundle

Overview

Collect all necessary diagnostic information for Algolia support tickets or internal troubleshooting. Uses real Algolia API endpoints to gather index stats, key permissions, and query performance data.

Prerequisites

ALGOLIA_APP_ID and ALGOLIA_ADMIN_KEY environment variables set
curl and jq available
Permission to read API key ACLs and index settings

Instructions

Step 1: Create the Debug Bundle Script

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

APP_ID="${ALGOLIA_APP_ID:?Set ALGOLIA_APP_ID}"
API_KEY="${ALGOLIA_ADMIN_KEY:?Set ALGOLIA_ADMIN_KEY}"
BUNDLE_DIR="algolia-debug-$(date +%Y%m%d-%H%M%S)"
BASE_URL="https://${APP_ID}-dsn.algolia.net"
HEADERS=(-H "X-Algolia-Application-Id: ${APP_ID}" -H "X-Algolia-API-Key: ${API_KEY}")

mkdir -p "$BUNDLE_DIR"

echo "=== Algolia Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" | tee -a "$BUNDLE_DIR/summary.txt"
echo "App ID: $APP_ID" | tee -a "$BUNDLE_DIR/summary.txt"

# 1. List all indices with record counts
echo "--- Indices ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "${BASE_URL}/1/indexes" "${HEADERS[@]}" \
  | jq '.items[] | {name, entries, dataSize, lastBuildTimeS}' \
  > "$BUNDLE_DIR/indices.json" 2>/dev/null
echo "Indices saved" >> "$BUNDLE_DIR/summary.txt"

# 2. Check API key permissions (redacted key)
echo "--- API Key ACL ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "${BASE_URL}/1/keys" "${HEADERS[@]}" \
  | jq '.keys[] | {description, acl, indexes, maxQueriesPerIPPerHour, validity}' \
  > "$BUNDLE_DIR/api-keys-acl.json" 2>/dev/null
echo "Key ACLs saved (keys redacted)" >> "$BUNDLE_DIR/summary.txt"

# 3. Get recent query logs (last 1000)
echo "--- Query Logs ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "${BASE_URL}/1/logs?length=100&type=all" "${HEADERS[@]}" \
  | jq '.logs[] | {timestamp, method, url, answer_code, processing_time_ms, query_nb_hits}' \
  > "$BUNDLE_DIR/query-logs.json" 2>/dev/null
echo "Last 100 log entries saved" >> "$BUNDLE_DIR/summary.txt"

# 4. Network connectivity test
echo "--- Network Diagnostics ---" >> "$BUNDLE_DIR/summary.txt"
for host in "${APP_ID}-dsn.algolia.net" "${APP_ID}-1.algolianet.com" "${APP_ID}-2.algolianet.com"; do
  RESULT=$(curl -s -o /dev/null -w "%{http_code},%{time_total}" "https://${host}/1/indexes" "${HEADERS[@]}" 2>/dev/null || echo "FAILED")
  echo "  ${host}: ${RESULT}" >> "$BUNDLE_DIR/summary.txt"
done

# 5. SDK version
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
node --version >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "node: not found" >> "$BUNDLE_DIR/summary.txt"
npm list algoliasearch 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "algoliasearch: not installed" >> "$BUNDLE_DIR/summary.txt"

# 6. Algolia service status
echo "--- Algolia Status ---" >> "$BUNDLE_DIR/summary.txt"
curl -s https://status.algolia.com/api/v2/status.json \
  | jq -r '.status.description' >> "$BUNDLE_DIR/summary.txt" 2>/dev/null

# Package (API keys already excluded from raw responses)
tar -czf "${BUNDLE_DIR}.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo ""
echo "Bundle created: ${BUNDLE_DIR}.tar.gz"

Step 2: Programmatic Debug Data Collection

import { algoliasearch } from 'algoliasearch';

async function collectDebugInfo() {
  const client = algoliasearch(
    process.env.ALGOLIA_APP_ID!,
    process.env.ALGOLIA_ADMIN_KEY!
  );

  const debug: Record<string, any> = {};

  // Index list and stats
  const { items } = await client.listIndices();
  debug.indices = items.map(i => ({
    name: i.name,
    entries: i.entries,
    dataSize: i.dataSize,
    lastBuildTimeS: i.lastBuildTimeS,
  }));

  // Per-index settings for problematic index
  const indexName = 'products'; // Target index
  try {
    debug.settings = await client.getSettings({ indexName });
  } catch (e) {
    debug.settings = `Failed: ${e}`;
  }

  // Recent logs
  const { logs } = await client.getLogs({
    indexName,
    length: 50,
    type: 'error',  // 'all' | 'query' | 'build' | 'error'
  });
  debug.recentErrors = logs.map(l => ({
    timestamp: l.timestamp,
    method: l.method,
    answerCode: l.answer_code,
    processingTimeMs: l.processing_time_ms,
  }));

  // API key used (check its ACL)
  try {
    const keyInfo = await client.getApiKey({
      key: process.env.ALGOLIA_ADMIN_KEY!,
    });
    debug.currentKeyAcl = keyInfo.acl;
  } catch (e) {
    debug.currentKeyAcl = 'Unable to read key ACL';
  }

  return debug;
}

Sensitive Data Handling

ALWAYS REDACT before sharing:

Full API keys (only share last 4 chars)
User PII in query logs
Internal hostnames or IPs

Safe to include:

App ID (it's in every frontend bundle)
Error codes and status codes
Index names and record counts
SDK and Node.js versions
Processing times and latencies

Error Handling

Issue	Cause	Solution
`getLogs` returns empty	Logs retention is 7 days (Grow) or 30 days (Premium)	Run sooner after incident
`getApiKey` 403	Non-admin key can only read its own info	Use Admin key
curl returns `000`	DNS or firewall blocking	Check outbound HTTPS to `*.algolia.net`
No `jq` available	Not installed	`apt install jq` or parse JSON differently

Resources

Next Steps

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