Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/glean-debug-bundle/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill glean-debug-bundle. Copyright stays with the author (MIT).

Glean Debug Bundle

Overview

This debug bundle collects diagnostic evidence from Glean enterprise search integrations for troubleshooting datasource configuration, document indexing pipelines, and search quality issues. It captures indexing token validation, datasource configuration state, crawl status, search query test results, and permission model health. The resulting tarball provides the evidence needed to diagnose connector failures, stale index problems, missing document results, and permission-based search gaps without requiring admin console access.

Prerequisites

• curl, jq, tar installed
• GLEAN_DOMAIN set to your Glean instance (e.g., your-company-be.glean.com)
• GLEAN_INDEXING_TOKEN for datasource/indexing endpoints
• GLEAN_CLIENT_TOKEN for search API endpoints

Debug Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE="debug-glean-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Environment ===" > "$BUNDLE/environment.txt"
echo "Glean Domain: ${GLEAN_DOMAIN:-NOT SET}" >> "$BUNDLE/environment.txt"
echo "Indexing Token: ${GLEAN_INDEXING_TOKEN:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Client Token: ${GLEAN_CLIENT_TOKEN:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo 'not installed')" >> "$BUNDLE/environment.txt"
echo "Timestamp: $(date -u)" >> "$BUNDLE/environment.txt"

# Datasource configuration
echo "=== Datasource Config ===" > "$BUNDLE/datasource-config.json"
curl -sf -X POST "https://${GLEAN_DOMAIN}/api/index/v1/getdatasourceconfig" \
  -H "Authorization: Bearer ${GLEAN_INDEXING_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"datasource\":\"${GLEAN_DATASOURCE:-custom}\"}" \
  >> "$BUNDLE/datasource-config.json" 2>&1 || echo '{"error":"UNREACHABLE"}' > "$BUNDLE/datasource-config.json"

# Indexing status check
echo "=== Indexing Status ===" > "$BUNDLE/indexing-status.json"
curl -sf -X POST "https://${GLEAN_DOMAIN}/api/index/v1/getstatus" \
  -H "Authorization: Bearer ${GLEAN_INDEXING_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"datasource\":\"${GLEAN_DATASOURCE:-custom}\"}" \
  >> "$BUNDLE/indexing-status.json" 2>&1 || echo '{"error":"FAILED"}' > "$BUNDLE/indexing-status.json"

# Search quality test
echo "=== Search Test ===" > "$BUNDLE/search-test.json"
curl -sf -X POST "https://${GLEAN_DOMAIN}/api/client/v1/search" \
  -H "Authorization: Bearer ${GLEAN_CLIENT_TOKEN}" \
  -H "X-Glean-Auth-Type: BEARER" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","pageSize":3}' \
  >> "$BUNDLE/search-test.json" 2>&1 || echo '{"error":"SEARCH_FAILED"}' > "$BUNDLE/search-test.json"

# Recent indexing logs
echo "=== Recent Logs ===" > "$BUNDLE/app-logs.txt"
tail -100 /var/log/glean-connector/*.log >> "$BUNDLE/app-logs.txt" 2>/dev/null || echo "No connector logs found" >> "$BUNDLE/app-logs.txt"

# Rate limit status
echo "=== Rate Limits ===" > "$BUNDLE/rate-limits.txt"
curl -sI -X POST "https://${GLEAN_DOMAIN}/api/index/v1/getdatasourceconfig" \
  -H "Authorization: Bearer ${GLEAN_INDEXING_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}' 2>/dev/null | grep -i "x-rate\|retry-after\|x-ratelimit" >> "$BUNDLE/rate-limits.txt" || echo "No rate limit headers" >> "$BUNDLE/rate-limits.txt"

# Package versions
echo "=== Dependencies ===" > "$BUNDLE/deps.txt"
npm ls 2>/dev/null | grep -i glean >> "$BUNDLE/deps.txt" || echo "No Glean npm packages found" >> "$BUNDLE/deps.txt"
pip list 2>/dev/null | grep -i glean >> "$BUNDLE/deps.txt" || echo "No Glean pip packages found" >> "$BUNDLE/deps.txt"

tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

Analyzing the Bundle

tar -xzf debug-glean-*.tar.gz
cat debug-glean-*/environment.txt               # Verify tokens are set
jq '.objectType' debug-glean-*/datasource-config.json  # Check datasource type
jq '.status' debug-glean-*/indexing-status.json  # Verify crawl state
jq '.results | length' debug-glean-*/search-test.json  # Count search results

Common Issues

Automated Health Check

async function checkGleanHealth(): Promise<{
  status: string;
  latencyMs: number;
  indexing: boolean;
  searchWorking: boolean;
}> {
  const domain = process.env.GLEAN_DOMAIN;
  const indexToken = process.env.GLEAN_INDEXING_TOKEN;
  const clientToken = process.env.GLEAN_CLIENT_TOKEN;
  const start = Date.now();

  const indexRes = await fetch(`https://${domain}/api/index/v1/getdatasourceconfig`, {
    method: "POST",
    headers: { Authorization: `Bearer ${indexToken}`, "Content-Type": "application/json" },
    body: JSON.stringify({ datasource: process.env.GLEAN_DATASOURCE || "custom" }),
  });

  const searchRes = await fetch(`https://${domain}/api/client/v1/search`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${clientToken}`,
      "X-Glean-Auth-Type": "BEARER",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: "test", pageSize: 1 }),
  });

  return {
    status: indexRes.ok && searchRes.ok ? "healthy" : "degraded",
    latencyMs: Date.now() - start,
    indexing: indexRes.ok,
    searchWorking: searchRes.ok,
  };
}

Instructions

1. Start with a synthetic probe and a bounded time window; collect status codes, timing bands, configuration revisions, and opaque correlation IDs only.
2. Redact or exclude authorization headers, tokens, query text, document bodies, result snippets, user identifiers, and group membership before writing the bundle.
3. Compare connector freshness, index status, rate-limit state, and synthetic allow/deny outcomes with the last known-good baseline.
4. Encrypt the bundle in the approved incident location, grant the minimum support audience, and delete it at the stated retention date.

Output

Create a redacted debug bundle manifest with incident ID, collection window, components checked, correlation IDs, aggregate counts, policy/config revisions, probe outcomes, owner, destination, and retention date. The manifest must not contain sensitive source data.

Error Handling

Stop collection if redaction cannot be verified, the requested destination is unapproved, or a command would expose a production credential. Record the blocked evidence class and escalate to the incident owner; do not bypass the collection policy for urgency.

Examples

incident=inc-opaque-12; window=15m; source=sandbox-guides; index_age=12m; allow=pass; deny=pass; destination=restricted-support; retention=7d is a useful, non-sensitive bundle summary.

Resources

• Glean Developer Portal
• Glean Status Page
• Glean Indexing API Reference

Next Steps

See glean-rate-limits.