algolia-debug-bundle

name	algolia-debug-bundle
description	Collect Algolia debug evidence: index stats, API key ACLs, query logs, and network diagnostics for support tickets. Trigger: "algolia debug", "algolia support bundle", "collect algolia logs", "algolia diagnostic", "algolia troubleshoot".
allowed-tools	Read, Bash(curl:*), Bash(npm:*), Bash(tar:*), Bash(jq:*), Grep
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","search","algolia"]
compatibility	Designed for Claude Code

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

Examples

The bundle script below is the support-ready example. It gathers configuration and response metadata into a timestamped directory while redacting secret values from the collected files.

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" >> 


  >> 
curl -s   \
  | jq  \
  >  2>/dev/null
  >> 


  >> 
curl -s   \
  | jq  \
  >  2>/dev/null
  >> 


  >> 
 host    ; 
  RESULT=$(curl -s -o /dev/null -w    2>/dev/null ||  )
    >> 



  >> 
node --version >>  2>/dev/null ||   >> 
npm list algoliasearch 2>/dev/null >>  ||   >> 


  >> 
curl -s https://status.algolia.com/api/v2/status.json \
  | jq -r  >>  2>/dev/null


tar -czf  
 -rf 
 
 

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,
    : ,
    : ,  
  });
  debug. = logs.( ({
    : l.,
    : l.,
    : l.,
    : l.,
  }));

  
   {
     keyInfo =  client.({
      : process..!,
    });
    debug. = keyInfo.;
  }  (e) {
    debug. = ;
  }

   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

Output

The command creates a timestamped diagnostic bundle containing index, key-permission, and query-health evidence suitable for an internal incident or Algolia support ticket, without including raw API keys.

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

• Algolia Logs API
• Algolia Status Page
• Algolia Support

Next Steps

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