Clari Debug Bundle

Overview

Collect Clari API diagnostic information for support: API connectivity, forecast list, job history, and error responses. All secrets are redacted.

Prerequisites

Authorized diagnostic access to the affected environment
CLARI_API_KEY injected by an approved secret mechanism
A secure local workspace with enough storage for the bundle
A support/incident record that defines what metadata may be shared

Instructions

Debug Bundle Script

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

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

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

# 1. API connectivity
echo "--- API Connectivity ---" >> "$BUNDLE_DIR/summary.txt"
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "apikey: ${CLARI_API_KEY}" \
  https://api.clari.com/v4/export/forecast/list)
echo "API Status: HTTP ${HTTP_CODE}" >> "$BUNDLE_DIR/summary.txt"

# 2. Forecast list (no sensitive data)
curl -s -H "apikey: ${CLARI_API_KEY}" \
  https://api.clari.com/v4/export/forecast/list \
  | jq '.forecasts[] | {forecastName, forecastId}' \
  > "$BUNDLE_DIR/forecasts.json" 2>&1

# 3. Recent export jobs
curl -s -H "apikey: ${CLARI_API_KEY}" \
  https://api.clari.com/v4/export/jobs \
  | jq '.jobs[] | {jobId, status, createdAt, forecastName}' \
  > "$BUNDLE_DIR/jobs.json" 2>&1

# 4. Environment info (redacted)
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "CLARI_API_KEY: ${CLARI_API_KEY:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
python3 --version >> "$BUNDLE_DIR/summary.txt" 2>&1
pip3 show requests 2>/dev/null | grep Version >> "$BUNDLE_DIR/summary.txt" || true

# 5. Package
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo "Bundle: $BUNDLE_DIR.tar.gz"

Safe to share: Forecast names, job IDs, HTTP status codes, library versions. Never share: API key, forecast amounts, rep names, email addresses.

Error Handling

Condition	Response
API request fails or times out	Keep the HTTP status and timestamp, then stop rather than repeatedly retrying.
Bundle contains unexpected sensitive data	Quarantine it, redact or regenerate it, and do not attach it externally.
Archive creation fails	Preserve the unarchived directory locally, diagnose storage/permissions, then clean it under retention policy.
Support needs additional fields	Obtain data-owner approval before collecting or sharing them.

Output

Generate a timestamped, redacted archive and a summary with environment, sanitized connectivity status, job IDs, collection failures, and integrity review decision. The archive is support evidence, not a data-export mechanism; it must exclude live credentials and individual forecast records.

Examples

During a failed scheduled export, generate the bundle, inspect summary.txt and JSON files locally, and remove any unapproved identifiers before attaching the archive to the named support case. If the provider is returning 429, include the redacted timestamps and job state rather than continuing to poll it.

Resources

Next Steps

For rate limit handling, see clari-rate-limits.