memory_get_peak_usage() with "real usage"

memory_get_peak_usage() with "real usage"

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

memory_get_peak_usage() with "real usage"

When debugging a PHP application that hits its memory ceiling, developers often reach for memory_get_peak_usage(). The function provides two distinct metrics depending on the boolean flag passed as an argument. Understanding the difference between these modes is critical when determining if your script was actually close to the configured limit in php.ini.

If you pass false (or omit the argument entirely), PHP returns the peak memory usage tracked by the Zend allocator's internal accounting, specifically emalloc(). This value represents how much of the requested heap the engine has consumed. It is a reliable indicator of your application's internal allocation behavior but ignores OS-level overheads like page table entries and kernel structures.

Conversely, when you pass true for the real_usage argument, PHP attempts to report the actual amount of memory allocated from the operating system. This figure includes the memory used by the Zend allocator plus any additional memory reserved by the underlying C library (often libc) or the OS itself. On systems using Linux with jemalloc or tcmalloc, this number might reflect the virtual address space committed by the runtime, which can be significantly higher than the emalloc() count.

Which Metric Matters for Memory Limits?

The core question is determining which value tells you if your script was near the memory_limit directive. The answer depends entirely on how memory_limit is enforced and what "hit" means in your specific context.

If your goal is to know if PHP stopped execution because it exceeded the limit set in php.ini, the false mode (internal allocation) is often the most accurate proxy. PHP's memory limit check operates strictly against the amount of memory reported by the Zend allocator (emalloc). When memory_get_peak_usage(false) returns a value approaching your memory_limit, you are effectively seeing the same metric that triggered the fatal error.

However, if you encounter an "Out of Memory" error from the operating system before PHP's limit kicks in, or if you are running on a platform where the allocator reserves memory differently (like using a custom heap manager), the real_usage flag becomes necessary. In these scenarios, memory_get_peak_usage(true) reveals how close the process got to exhausting physical RAM or swapping space, regardless of what PHP thinks is its limit.

Practical Implementation

To monitor this behavior in production or during profiling, you can wrap your logic in a helper that captures both metrics:

$peakEmalloc = memory_get_peak_usage(false);
$peakRealUsage = memory_get_peak_usage(true);

// Convert to MB for readability
$peakEmallocMB = round($peakEmalloc / 1024 / 1024, 3);
$peakRealUsageMB = round($peakRealUsage / 1024 / 1024, 3);

echo "Zend Allocator Peak: {$peakEmallocMB} MB\n";
echo "OS Real Usage Peak: {$peakRealUsageMB} MB\n";

When analyzing logs from a crash, compare these numbers against your memory_limit. If the script dies at 512M and $peakEmallocMB is roughly 509, you hit the PHP limit. If $peakRealUsageMB spikes to 600M while $peakEmallocMB stays low, your issue lies in OS-level fragmentation or allocator overhead, not the PHP configuration.

Trade-offs and Limitations

Relying on memory_get_peak_usage() has inherent limitations that must be acknowledged. The function reflects the memory usage of the current request scope (or process lifetime if using CLI with memory_get_usage without arguments). It does not account for memory deallocated by garbage collection between requests in persistent contexts unless you explicitly call gc_collect_cycles().

Furthermore, on systems where the allocator uses mmap heavily or uses transparent huge pages, the "real" usage reported by the OS might differ from the actual resident set size (RSS). The true argument attempts to provide a more holistic view of the process footprint but can sometimes report numbers that seem inflated compared to the PHP limit because they include page tables and other kernel metadata.

For high-traffic applications, especially those using frameworks like Laravel, relying solely on these metrics might mask issues related to persistent memory leaks in long-running processes. In such cases, continuous profiling tools that track RSS over time provide a more granular view than a single snapshot from memory_get_peak_usage().

If you are looking for deeper insights into how PHP manages memory under different allocator backends or specific OS configurations, resources like https://laravelcompany.com offer relevant discussions on performance tuning that can help contextualize these metrics within a broader optimization strategy.

Our network