openevidence-debug-bundle

name	openevidence-debug-bundle
description	Generate comprehensive debug information for OpenEvidence integration issues. Use when troubleshooting complex problems, preparing support tickets, or conducting post-incident analysis. Trigger with phrases like "openevidence debug", "openevidence troubleshoot", "openevidence support bundle", "diagnose openevidence".
allowed-tools	Read, Grep, Bash(curl:*), Bash(npm:*), Bash(node:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

OpenEvidence Debug Bundle

Overview

Generate comprehensive diagnostic information for troubleshooting OpenEvidence integration issues without exposing PHI.

Prerequisites

• OpenEvidence SDK installed
• Access to application logs
• Command-line access
• curl installed

Instructions

Step 1: Environment Check Script

#!/bin/bash
# scripts/openevidence-debug.sh

echo "=== OpenEvidence Debug Bundle ==="
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo ""

# 1. Environment Variables (masked)
echo "=== Environment Configuration ==="
echo "OPENEVIDENCE_API_KEY: ${OPENEVIDENCE_API_KEY:+[SET - ${#OPENEVIDENCE_API_KEY} chars]}"
echo "OPENEVIDENCE_ORG_ID: ${OPENEVIDENCE_ORG_ID:+[SET - ${#OPENEVIDENCE_ORG_ID} chars]}"
echo "OPENEVIDENCE_BASE_URL: ${OPENEVIDENCE_BASE_URL:-https://api.openevidence.com}"
echo "OPENEVIDENCE_TIMEOUT: ${OPENEVIDENCE_TIMEOUT:-30000}ms"
echo "NODE_ENV: ${NODE_ENV:-not set}"
echo ""

# 2. SDK Version
echo "=== SDK Version ==="
npm list @openevidence/sdk 2>/dev/null || pip show openevidence 2>/dev/null || echo "SDK not found"
echo ""

# 3. Node/Python Version
echo "=== Runtime Version ==="
node --version 2>/dev/null || echo "Node.js not found"
python3 --version 2>/dev/null || echo "Python not found"
echo ""

# 4. Connectivity Test
echo "=== Connectivity Test ==="
HEALTH_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${OPENEVIDENCE_API_KEY}" \
  "${OPENEVIDENCE_BASE_URL:-https://api.openevidence.com}/health" 2>/dev/null)
echo "Health endpoint: HTTP ${HEALTH_STATUS}"

DNS_CHECK=$(dig +short api.openevidence.com 2>/dev/null || echo "DNS lookup failed")
echo "DNS resolution: ${DNS_CHECK}"
echo ""

# 5. TLS Check
echo "=== TLS Configuration ==="
openssl s_client -connect api.openevidence.com:443 -brief 2>/dev/null | head -5 || echo "TLS check failed"
echo ""

# 6. Rate Limit Status
echo "=== Rate Limit Status ==="
curl -s -D - \
  -H "Authorization: Bearer ${OPENEVIDENCE_API_KEY}" \
  "${OPENEVIDENCE_BASE_URL:-https://api.openevidence.com}/v1/rate-limit" 2>/dev/null \
  | grep -i "x-ratelimit" || echo "Could not retrieve rate limit headers"
echo ""

echo "=== Debug Bundle Complete ==="

Step 2: Programmatic Debug Collection

// src/debug/debug-bundle.ts
import { OpenEvidenceClient } from '@openevidence/sdk';
import { execSync } from 'child_process';

interface DebugBundle {
  timestamp: string;
  environment: EnvironmentInfo;
  connectivity: ConnectivityInfo;
  sdkInfo: SDKInfo;
  recentErrors: ErrorSummary[];
  metrics: MetricsSummary;
}

interface EnvironmentInfo {
  nodeVersion: string;
  sdkVersion: string;
  apiKeySet: boolean;
  apiKeyLength: number;
  orgIdSet: boolean;
  baseUrl: string;
  timeout: number;
}

interface ConnectivityInfo {
  healthStatus: number | null;
  latencyMs: number | null;
  dnsResolution: boolean;
  tlsVersion: string | null;
}

interface  {
  : ;
  : [];
}

  {
  : ;
  : ;
  : ;
}

  {
  : ;
  : ;
  : ;
  : ;
}

   (): <> {
   timestamp =  ().();

  
   environment = ();

  
   connectivity =  ();

  
   sdkInfo = ();

  
   recentErrors =  ();

  
   metrics =  ();

   {
    timestamp,
    environment,
    connectivity,
    sdkInfo,
    recentErrors,
    metrics,
  };
}

 ():  {
   {
    : process.,
    : (),
    : !!process..,
    : process..?. || ,
    : !!process..,
    : process.. || ,
    : (process.. || ),
  };
}

  (): <> {
   baseUrl = process.. || ;
   startTime = .();

   {
     response =  (, {
      : { :  },
    });

     {
      : response.,
      : .() - startTime,
      : ,
      : , 
    };
  }  (: ) {
     {
      : ,
      : ,
      : error. !== ,
      : ,
    };
  }
}

 ():  {
   {
    : (),
    : [, , ],
  };
}

 ():  {
   {
     result = (, { :  });
     json = .(result);
     json.?.[pkg]?. || ;
  }  {
     ;
  }
}

  (): <[]> {
  
  
   [];
}

  (): <> {
  
  
   {
    : ,
    : ,
    : ,
    : ,
  };
}

Step 3: Sanitized Log Extraction

// src/debug/log-sanitizer.ts
// IMPORTANT: Removes PHI before including in debug bundle

const PHI_PATTERNS = [
  /\b\d{3}-\d{2}-\d{4}\b/g,           // SSN
  /\b[A-Z]\d{8}\b/gi,                  // MRN patterns
  /\b\d{10,}\b/g,                      // Long numbers (potential IDs)
  /patient[_\s]*(name|id|dob)/gi,      // Patient fields
  /\b(male|female),?\s*\d{1,3}/gi,    // Demographics
  /"name"\s*:\s*"[^"]+"/gi,           // Name fields in JSON
  /"dob"\s*:\s*"[^"]+"/gi,            // DOB fields
  /"mrn"\s*:\s*"[^"]+"/gi,            // MRN fields
];

export function sanitizeLogs(logs: string): string {
  let sanitized = logs;

  for (const pattern of PHI_PATTERNS) {
    sanitized = sanitized.replace(pattern, '[REDACTED]');
  }

  return sanitized;
}

export function extractSanitizedLogs(
  logSource: string,
  timeRange: { start: Date; end: Date },
  maxLines: number = 1000
): [] {
  
  

   : [] = [];
  
  

   logs.(sanitizeLogs).(, maxLines);
}

Step 4: Support Ticket Generator

// src/debug/support-ticket.ts
import { generateDebugBundle, DebugBundle } from './debug-bundle';
import { sanitizeLogs, extractSanitizedLogs } from './log-sanitizer';

interface SupportTicket {
  subject: string;
  description: string;
  debugBundle: DebugBundle;
  sanitizedLogs: string[];
  stepsToReproduce: string[];
  expectedBehavior: string;
  actualBehavior: string;
}

export async function generateSupportTicket(
  issue: {
    summary: string;
    stepsToReproduce: string[];
    expectedBehavior: string;
    actualBehavior: string;
  }
): Promise<SupportTicket> {
  const bundle = await generateDebugBundle();

  const logs = extractSanitizedLogs(
    '/var/log/app/openevidence.log',
    { start: new Date(Date.now() - 3600000), end: new () },
    
  );

   {
    : ,
    : ,
    : bundle,
    : logs,
    : issue.,
    : issue.,
    : issue.,
  };
}

Output

• Environment configuration status
• Connectivity test results
• SDK version information
• Sanitized logs (no PHI)
• Formatted support ticket

Diagnostic Checklist

• API key is set and correct length
• Organization ID is configured
• Health endpoint returns 200
• DNS resolves api.openevidence.com
• TLS handshake succeeds
• Rate limits have headroom
• No recent 5xx errors

Error Handling

Issue	Check	Resolution
No connectivity	DNS, firewall	Check network config
Auth failures	API key format	Regenerate key in dashboard
Timeouts	Latency test	Increase timeout, check network
PHI in logs	Log sanitizer	Audit logging configuration

Examples

Quick Debug Command

# Run bash debug script
chmod +x scripts/openevidence-debug.sh
./scripts/openevidence-debug.sh > debug-bundle.txt

Generate Support Ticket

const ticket = await generateSupportTicket({
  summary: 'Clinical queries timing out after SDK upgrade',
  stepsToReproduce: [
    '1. Upgrade @openevidence/sdk to v2.0.0',
    '2. Make clinical query request',
    '3. Request times out after 30s',
  ],
  expectedBehavior: 'Response within 10s',
  actualBehavior: 'Timeout after configured limit',
});

console.log(JSON.stringify(ticket, null, 2));

Resources

• OpenEvidence Support
• OpenEvidence Status

Next Steps

For rate limit management, see openevidence-rate-limits.