Algolia Debug Bundle Skill

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.

Agent Skills: Algolia Debug Bundle

Install this agent skill to your local

Skill Files