Advanced debugging tools for development, troubleshooting, and system analysis with HTTP capture and LLM output monitoring

Debug Configuration

CoAI.Dev's debug mode provides powerful development and troubleshooting tools that allow developers to capture all HTTP inputs, monitor LLM outputs, and analyze system behavior in real-time. This comprehensive debugging system is essential for development, troubleshooting, and system optimization.

Overview

Debug mode offers:

🔍 HTTP Input Capture: Complete interception of all HTTP requests
🤖 LLM Output Monitoring: Full capture of all AI model outputs
📡 Event Stream Analysis: Real-time monitoring of streaming responses
🛠️ Development Tools: Advanced debugging capabilities for developers
📊 Performance Analysis: Detailed timing and performance metrics
🔧 Troubleshooting: Comprehensive error tracking and diagnosis
📋 Request/Response Logging: Complete transaction logging
⚡ Real-time Monitoring: Live system behavior observation

Development and Production Use

Debug mode is designed for development environments and controlled production troubleshooting. Use with caution in production as it captures sensitive data and may impact performance.

Core Features

HTTP Input Capture

Complete Request Interception:

Debug mode captures every HTTP request with full detail:

HTTP Header Analysis

Capture and analyze all HTTP headers:

Captured Headers:

Content-Type: Request content type and encoding
User-Agent: Client browser and platform information
Authorization: Authentication tokens and credentials
Accept: Client's accepted response formats
Origin: Request origin for CORS analysis
Custom Headers: Application-specific headers

Header Analysis Example:

{
  "request_headers": {
    "content-type": "application/json",
    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
    "accept": "application/json, text/plain, */*",
    "origin": "https://chat.example.com",
    "x-request-id": "req_12345678",
    "x-forwarded-for": "192.168.1.100",
    "referer": "https://chat.example.com/chat"
  }
}

Security Analysis:

Authentication method validation
Security header presence checking
CORS policy verification
Request origin validation
Token format and expiration analysis

LLM Output Monitoring

Complete AI Model Response Capture:

Response Content Capture

Monitor all AI model outputs with detailed analysis:

Output Types:

Text Responses: Complete text generation
Streaming Responses: Real-time streaming content
Error Responses: Error messages and codes
Metadata: Response timing and token usage
Partial Responses: Incomplete or interrupted responses

{
  "llm_output": {
    "model": "gpt-4",
    "response_type": "streaming",
    "content": "Quantum computing is a revolutionary computing paradigm...",
    "token_count": {
      "input_tokens": 12,
      "output_tokens": 287,
      "total_tokens": 299
    },
    "response_time": "2.34s",
    "streaming_chunks": 47,
    "completion_reason": "stop"
  }
}

Performance Metrics

Track detailed performance information:

Timing Analysis:

Request Processing Time: Total time from request to response
Model Processing Time: AI model inference time
Queue Wait Time: Time spent waiting in processing queue
Network Latency: Network transmission delays
Streaming Latency: Time between streaming chunks

{
  "performance_metrics": {
    "total_time": "2.45s",
    "breakdown": {
      "queue_wait": "0.05s",
      "model_processing": "2.15s",
      "response_formatting": "0.12s",
      "network_transfer": "0.13s"
    },
    "throughput": {
      "tokens_per_second": 123.4,
      "characters_per_second": 587.2
    }
  }
}

Error Analysis

Comprehensive error tracking and analysis:

Error Categories:

Model Errors: AI service provider errors
Network Errors: Connectivity and timeout issues
Authentication Errors: Authorization failures
Rate Limit Errors: Quota and rate limiting issues
Validation Errors: Input validation failures

{
  "error_analysis": {
    "error_occurred": true,
    "error_type": "rate_limit_exceeded",
    "error_code": "429",
    "error_message": "Too many requests",
    "provider_error": {
      "provider": "openai",
      "original_error": "Rate limit exceeded"
    },
    "retry_info": {
      "retry_after": "60s",
      "max_retries": 3,
      "current_attempt": 1
    }
  }
}

Event Stream Analysis

Real-time Streaming Monitoring:

Stream Processing:

Chunk Analysis: Individual streaming chunk inspection
Connection Monitoring: WebSocket and SSE connection tracking
Flow Control: Backpressure and buffering analysis
Error Recovery: Stream interruption and recovery tracking
Performance Optimization: Streaming efficiency analysis

Event Stream Example:

{
  "event_stream": {
    "connection_id": "conn_abc123",
    "stream_type": "server_sent_events",
    "chunk_count": 47,
    "chunks": [
      {
        "sequence": 1,
        "timestamp": "2024-01-20T10:30:15.123Z",
        "data": "data: {\"choices\":[{\"delta\":{\"content\":\"Quantum\"}}]}\n\n",
        "size_bytes": 45,
        "processing_time": "0.012s"
      },
      {
        "sequence": 2,
        "timestamp": "2024-01-20T10:30:15.145Z",
        "data": "data: {\"choices\":[{\"delta\":{\"content\":\" computing\"}}]}\n\n",
        "size_bytes": 52,
        "processing_time": "0.015s"
      }
    ],
    "stream_stats": {
      "total_size": "12.3KB",
      "average_chunk_size": "261 bytes",
      "stream_duration": "2.34s",
      "average_chunk_interval": "0.05s"
    }
  }
}

Configuration and Setup

Enable Debug Mode

Access Debug Settings

Navigate to debug configuration:

Admin Panel: Go to Admin Panel → System Settings
Debug Section: Find Debug Configuration section
Enable Debug Mode: Check the Debug Mode checkbox
Configure Options: Set debug scope and output options
Save Settings: Click Save to activate debug mode

{
  "debug_configuration": {
    "enabled": true,
    "capture_http_input": true,
    "capture_llm_output": true,
    "log_event_streams": true,
    "include_headers": true,
    "include_body": true,
    "include_performance_metrics": true
  }
}

Configure Debug Scope

Set what information to capture:

Capture Options:

HTTP Requests: All incoming HTTP requests
HTTP Responses: All outgoing HTTP responses
LLM Interactions: AI model requests and responses
Database Queries: Database interaction logging
Cache Operations: Cache hit/miss and operations
External API Calls: Third-party service calls

Scope Configuration:

{
  "debug_scope": {
    "http_capture": {
      "include_headers": true,
      "include_body": true,
      "include_query_params": true,
      "max_body_size": "1MB"
    },
    "llm_capture": {
      "include_prompts": true,
      "include_responses": true,
      "include_metadata": true,
      "include_performance": true
    },
    "filtering": {
      "exclude_static_assets": true,
      "exclude_health_checks": true,
      "user_id_filter": [],
      "endpoint_filter": []
    }
  }
}

Output Configuration

Configure how debug information is displayed:

Output Formats:

Console Output: Real-time console logging
File Logging: Structured log file output
Web Interface: Browser-based debug console
API Endpoints: Programmatic debug data access
External Integration: Send debug data to external tools

Output Settings:

{
  "debug_output": {
    "console_enabled": true,
    "file_logging": {
      "enabled": true,
      "file_path": "/var/log/chatnio/debug.log",
      "rotation": "daily",
      "max_size": "100MB"
    },
    "web_interface": {
      "enabled": true,
      "access_control": "admin_only",
      "real_time_updates": true
    },
    "external_integrations": [
      {
        "type": "elasticsearch",
        "endpoint": "https://es-cluster.example.com",
        "index": "chatnio-debug"
      }
    ]
  }
}

Security and Privacy

Debug Mode Security Considerations:

Security Warning

Debug mode captures sensitive information including authentication tokens, user data, and API keys. Ensure proper access controls and data protection when debug mode is enabled.

Security Measures:

Access Control: Restrict debug mode access to authorized users
Data Masking: Automatically mask sensitive information
Audit Logging: Log all debug mode access and configuration changes
Time Limits: Set automatic debug mode expiration
Environment Isolation: Use only in development/staging environments

Privacy Configuration:

{
  "debug_security": {
    "access_control": {
      "required_role": "admin",
      "ip_whitelist": ["192.168.1.0/24"],
      "session_timeout": "1_hour"
    },
    "data_protection": {
      "mask_auth_tokens": true,
      "mask_user_data": true,
      "mask_api_keys": true,
      "retention_period": "24_hours"
    },
    "audit_trail": {
      "log_access": true,
      "log_configuration_changes": true,
      "alert_on_sensitive_access": true
    }
  }
}

Debug Interface and Tools

Web-Based Debug Console

Real-time Debug Dashboard:

Live Request Monitoring

Real-time HTTP request monitoring interface:

Monitor Features:

Live Request Feed: Real-time request stream
Request Filtering: Filter by endpoint, user, or method
Request Details: Expandable request information
Search and Filter: Advanced search capabilities
Export Options: Export captured requests

Interface Components:

// Debug console request monitor
const requestMonitor = {
  filters: {
    endpoint: "/api/v1/chat/completions",
    method: "POST",
    user_id: null,
    status_code: null
  },
  display: {
    auto_scroll: true,
    show_headers: true,
    show_body: true,
    max_entries: 1000
  },
  export: {
    format: "json",
    include_responses: true,
    time_range: "last_1_hour"
  }
};

Request Timeline:

Chronological request ordering
Visual request/response pairing
Performance timeline visualization
Error highlighting and alerts
Statistical summaries and trends

Development Workflow Integration

IDE Integration

Development Environment Support:

Supported IDEs:

Visual Studio Code: Debug extension and integration
IntelliJ IDEA: Plugin for debug data visualization
Sublime Text: Debug output integration
Vim/Neovim: Command-line debug tools
Web-based IDEs: Browser-based debug console

VS Code Extension Features:

{
  "vscode_extension": {
    "features": [
      "real_time_debug_output",
      "request_response_viewer",
      "performance_metrics",
      "error_highlighting",
      "debug_console_integration"
    ],
    "settings": {
      "auto_connect": true,
      "debug_server_url": "http://localhost:8000/debug",
      "refresh_interval": "1s"
    }
  }
}

API Integration

Programmatic Debug Access:

Debug API Endpoints:

# Get debug session status
GET /api/debug/status
 
# Retrieve captured requests
GET /api/debug/requests?limit=50&offset=0
 
# Get performance metrics
GET /api/debug/performance
 
# Export debug data
POST /api/debug/export
{
  "format": "json",
  "time_range": "last_1_hour",
  "include_responses": true
}

Webhook Integration:

{
  "debug_webhooks": {
    "error_alerts": {
      "url": "https://alerts.example.com/webhook",
      "events": ["critical_error", "high_error_rate"],
      "headers": {
        "Authorization": "Bearer webhook_token"
      }
    },
    "performance_alerts": {
      "url": "https://monitoring.example.com/webhook",
      "events": ["slow_response", "high_cpu"],
      "threshold_config": {
        "response_time": "5s",
        "cpu_usage": "90%"
      }
    }
  }
}

Best Practices

Development Usage

Effective Debug Mode Usage:

Development Workflow:

Enable Debug Mode: Turn on debug mode during development
Monitor Requests: Watch HTTP requests and responses in real-time
Analyze Performance: Identify performance bottlenecks early
Test Error Handling: Verify error handling and recovery
Optimize Configuration: Use debug data to optimize settings

Testing Integration:

Automated testing with debug data verification
Performance regression testing
Error simulation and recovery testing
Load testing with debug monitoring
Integration testing with external services

Production Troubleshooting

Controlled Production Debugging:

Safety Guidelines:

Limited Time Windows: Enable debug mode for specific time periods
Specific User/Endpoint Filtering: Target specific issues
Data Sanitization: Ensure sensitive data protection
Access Control: Restrict debug access to authorized personnel
Audit Trail: Maintain complete debug session logs

Incident Response:

{
  "incident_debug_protocol": {
    "activation_criteria": [
      "critical_error_rate > 5%",
      "response_time > 10s",
      "multiple_user_reports"
    ],
    "safety_measures": {
      "max_duration": "30_minutes",
      "auto_disable": true,
      "access_approval_required": true,
      "data_retention": "24_hours"
    },
    "escalation": {
      "notify_on_activation": ["dev_team", "ops_team"],
      "escalate_after": "15_minutes",
      "executive_notification": "critical_only"
    }
  }
}

Performance Impact

Debug Mode Optimization:

Performance Considerations:

Selective Capture: Only capture necessary debug information
Efficient Logging: Use asynchronous logging to minimize impact
Storage Management: Regular cleanup of debug data
Resource Monitoring: Monitor debug mode resource usage
Graceful Degradation: Automatic debug mode disabling under high load

Resource Management:

{
  "debug_performance": {
    "resource_limits": {
      "max_memory_usage": "512MB",
      "max_disk_usage": "2GB",
      "max_cpu_overhead": "5%"
    },
    "auto_throttling": {
      "high_load_threshold": "80%",
      "throttle_actions": [
        "reduce_capture_frequency",
        "disable_body_capture",
        "enable_sampling"
      ]
    },
    "cleanup_policies": {
      "retention_period": "48_hours",
      "cleanup_frequency": "hourly",
      "archive_before_delete": true
    }
  }
}

Debug Configuration provides essential development and troubleshooting capabilities for CoAI.Dev, enabling rapid issue identification, performance optimization, and system analysis. Continue with Call Records & API Logging for comprehensive usage tracking, or explore Advanced Features for enterprise capabilities.

Debug Configuration

On this page