Enhanced Debugging & Profiling Tools

[Thavarshan]

Summary

Add comprehensive debugging and profiling capabilities including request/response inspection, performance analysis, and detailed logging.

Motivation

Debugging tools are essential for:

• Development Efficiency: Quick identification of issues
• Performance Optimization: Detailed timing and resource usage analysis
• Production Debugging: Safe debugging in production environments
• API Understanding: Detailed request/response inspection
• Network Analysis: Connection and transfer statistics
• Memory Profiling: Memory usage tracking for large operations

Proposed API

// Debug mode with detailed logging
$response = fetch('/api/data')
    ->debug([
        'request_headers' => true,
        'request_body' => true,
        'response_headers' => true,
        'response_body' => 1024, // First 1KB
        'timing' => true,
        'memory' => true,
        'dns_resolution' => true,
    ]);

// Performance profiling
$profiler = new FetchProfiler();
$client = fetch_client()->withProfiler($profiler);

$response = $client->get('/api/endpoint');

$profile = $profiler->getProfile();
// Returns: DNS time, connect time, SSL time, transfer time, total time, etc.

Implementation Details

class DebugInfo
{
    public function __construct(
        private RequestInterface $request,
        private ?ResponseInterface $response,
        private array $timings,
        private array $connectionStats,
        private int $memoryUsage
    ) {}
    
    public function dump(): string
    {
        return json_encode([
            'request' => $this->formatRequest(),
            'response' => $this->formatResponse(),
            'performance' => $this->timings,
            'memory' => $this->memoryUsage,
        ], JSON_PRETTY_PRINT);
    }
}

class FetchProfiler
{
    private array $profiles = [];
    
    public function startProfile(string $requestId): void
    {
        $this->profiles[$requestId] = [
            'start_time' => microtime(true),
            'start_memory' => memory_get_usage(true),
            'dns_start' => null,
            'connect_start' => null,
            'ssl_start' => null,
            'transfer_start' => null,
        ];
    }
    
    public function recordEvent(string $requestId, string $event, float $timestamp): void
    {
        if (isset($this->profiles[$requestId])) {
            $this->profiles[$requestId][$event] = $timestamp;
        }
    }
    
    public function getProfile(string $requestId): ?array
    {
        return $this->profiles[$requestId] ?? null;
    }
}

Benefits

• Development Speed: Faster issue identification and resolution
• Performance Insights: Detailed performance metrics
• Production Safety: Non-intrusive debugging capabilities
• Learning Tool: Understand HTTP communication details

Priority

Medium Impact, Low Effort - Valuable for development but not critical for production functionality.

[github-actions]

This issue has been automatically marked as stale due to inactivity.