Profiler

Profiler

Razy includes a lightweight runtime performance profiler that captures memory, CPU, and timing snapshots at labeled checkpoints. Use it to identify bottlenecks, track memory growth, and measure execution time across code sections.

---

Table of Contents

• Quick Start
• Creating Checkpoints
• Generating Reports
• Captured Metrics
• API Reference

---

Quick Start

use Razy\Profiler;

$profiler = new Profiler(); // captures initial baseline

// ... do some work ...
$profiler->checkpoint('db_query');

// ... more work ...
$profiler->checkpoint('template_render');

// ... final work ...
$profiler->checkpoint('response_sent');

// Compare consecutive checkpoints
$report = $profiler->report();
print_r($report);

---

Creating Checkpoints

Each checkpoint captures a snapshot of the runtime state at that moment:

$profiler = new Profiler();

// Add labeled checkpoints at key points
$profiler->checkpoint('boot');
$profiler->checkpoint('routes_loaded');
$profiler->checkpoint('controller_executed');
$profiler->checkpoint('view_rendered');
$profiler->checkpoint('response_sent');

Rules:

• Labels must be non-empty strings
• Labels must be unique (throws on duplicates)
• The constructor captures an initial __init checkpoint automatically

---

Generating Reports

report() ??Consecutive Comparisons

Compare consecutive checkpoints to see deltas between each step:

// Compare all consecutive pairs
$report = $profiler->report();
// [
//   'boot ??routes_loaded' => [
//     'execution_time' => 0.0042,
//     'memory_usage'   => 524288,
//     ...
//   ],
//   'routes_loaded ??controller_executed' => [
//     'execution_time' => 0.0156,
//     ...
//   ],
// ]

// Compare specific checkpoints only
$report = $profiler->report(false, 'boot', 'controller_executed', 'response_sent');

// Compare each checkpoint against __init (total from start)
$report = $profiler->report(compareWithInit: true);
// [
//   '__init ??boot' => [...],
//   '__init ??routes_loaded' => [...],
//   '__init ??controller_executed' => [...],
// ]

reportTo() ??Single Comparison

Compare a specific checkpoint against the initial baseline:

$delta = $profiler->reportTo('controller_executed');
// [
//   'execution_time'   => 0.0198,    // seconds since __init
//   'memory_usage'     => 1048576,   // bytes change
//   'memory_allocated' => 2097152,   // bytes change
//   'output_buffer'    => 0,         // bytes change
//   'user_mode_time'   => 0.015,     // CPU seconds
//   'system_mode_time' => 0.003,     // CPU seconds
//   'defined_functions' => ['myFunc1', 'myFunc2'],  // new functions
//   'declared_classes'  => ['App\\MyController'],    // new classes
// ]

---

Captured Metrics

Each checkpoint captures the following data:

Metric	Type	Source	Description
memory_usage	int	memory_get_usage()	Heap memory in bytes
memory_allocated	int	memory_get_usage(true)	System-allocated memory in bytes
output_buffer	int	ob_get_length()	Output buffer size
user_mode_time	float	getrusage()	User CPU seconds
system_mode_time	float	getrusage()	System CPU seconds
execution_time	float	microtime(true)	Wall-clock time in seconds
defined_functions	array	get_defined_functions()	User-defined function names
declared_classes	array	get_declared_classes()	Declared class names

How Reports Compute Deltas

• Numeric metrics (memory, time): arithmetic difference (checkpoint - baseline)
• Array metrics (functions, classes): array_diff(checkpoint, baseline) ??shows new entries only

---

Use Cases

Measuring Database Query Time

$profiler = new Profiler();
$profiler->checkpoint('before_query');

$result = $db->query('SELECT * FROM users WHERE active = 1');

$profiler->checkpoint('after_query');
$delta = $profiler->reportTo('after_query');
echo "Query took: " . round($delta['execution_time'] * 1000, 2) . "ms\n";
echo "Memory delta: " . number_format($delta['memory_usage']) . " bytes\n";

Profiling an Entire Request

$profiler = new Profiler();

// Phase 1: Bootstrap
require 'bootstrap.php';
$profiler->checkpoint('bootstrap');

// Phase 2: Routing
$route = $router->match($request);
$profiler->checkpoint('routing');

// Phase 3: Controller
$response = $route->execute();
$profiler->checkpoint('controller');

// Phase 4: Rendering
echo $response->render();
$profiler->checkpoint('render');

// Full report
$report = $profiler->report(compareWithInit: true);
foreach ($report as $label => $metrics) {
    printf(
        "%s: %.2fms, %s memory\n",
        $label,
        $metrics['execution_time'] * 1000,
        number_format($metrics['memory_usage'])
    );
}

Detecting Class Table Bloat (Worker Mode)

$profiler = new Profiler();
$profiler->checkpoint('request_start');

// ... handle request ...

$profiler->checkpoint('request_end');
$delta = $profiler->reportTo('request_end');

if (count($delta['declared_classes']) > 50) {
    error_log('Warning: ' . count($delta['declared_classes']) . ' new classes loaded this request');
}

---

API Reference

Method	Signature	Description
__construct	()	Create profiler with initial __init checkpoint
checkpoint	(string $label): Profiler	Capture snapshot (throws on empty/duplicate)
report	(bool $compareWithInit = false, string ...$labels): array	Consecutive delta report
reportTo	(string $label): array	Compare checkpoint to __init

??Previous: RateLimiter FTP-SFTP