Garbage Collection Statistics

Xdebug's built-in garbage collection statistics profiler allows you to find out when the PHP internal garbage collector triggers, how many variables it was able to clean up, how long it took, and how how much memory was actually freed.

Introduction

New in Xdebug 2.6

Garbage Collection (GC) in PHP can have a serious impact on memory and performance, so understanding when it is triggered and how efficient each run is, allows you to optimise your programs. The PHP Engine does not provide a mechanism to gather statistics about garbage collection, but Xdebug now does.

For the time being, the garbage collection statistics are collected in a human readable, tabular format only, because there are no tools for this kind of report that we could generate machine readable output for. Future versions may include exports in other formats to allow machine processing.

Usage

There are two approaches to start collecting the GC statistics with two different use-cases.

By Settings

The first is entirely via INI settings and the primary use-case is to collect statistics for indiviual CLI script runs (where GC is often an issue).

php -dxdebug.gc_stats_enable=1 your_script.php

If you wish to collect the garbage collection statistics for every script that you execute, you can set the xdebug.gc_stats_enable INI setting on the system or directory-level. Be aware that activating the collection globally will produce an output file for every executed script, even if the garbage collector didn't run.

By Calling a Function

The second approach to starting collection is to call the function xdebug_start_gcstats() directly in your PHP script. This gives you more control over when statistics collection is started.

You can stop collection for both INI and function based approaches by calling xdebug_stop_gcstats().

Output

The default (and only for now) output format of Garbage Collection statistics is a tabular human readable text output.

The output format of Garbage Collection statistics is a tabular human readable text output.

Garbage Collection Report
version: 1
creator: xdebug 2.6.0 (PHP 7.2.0)

Collected | Efficiency% | Duration | Memory Before | Memory After | Reduction% | Function
----------+-------------+----------+---------------+--------------+------------+---------
    10000 |    100.00 % |  0.00 ms |       5539880 |       579880 |    79.53 % | bar
    10000 |    100.00 % |  0.00 ms |       5540040 |       580040 |    79.53 % | Garbage::produce
     4001 |     40.01 % |  0.00 ms |       2563048 |       578968 |    77.41 % | gc_collect_cycles

The header contains the version of the report and the version of Xdebug that generated it.

The table itself then contains one row for each garbage collection run each with 7 reported variables:

• Collected — The number of so called "roots" that have been garbage collected during this run. A "root" is either an PHP object (instance) or an array that is under observation by the Garbage Collector for potential cleanup.
• Efficiency% — Is the number of cleared roots divided by 10 000 - a magic number of "roots" when reached triggers PHPs internal garbage collector to run automatically.
• Duration — Denotes the duration in milliseconds that this garbage collection run took.
• Memory Before — Contains the memory as measured by memory_get_usage() before this GC run was activated.
• Memory After — Contains the memory as measured by memory_get_usage() after the GC run was finished.
• Reduction% — The percent reduction in memory due to this GC run.
• Function — The name of the function or method the GC run was triggered in. If it is gc_collect_cycles() then this means the Garbage Collector was triggered explicitly. All other values indicate the GC was triggered implicitly due to the 10 000 "roots" reached metric of the PHP engine.

For details on how PHPs garbage collection works see the PHP manuals chapter on Garbage Collection.

Related Settings and Functions

• bool xdebug.gc_stats_enable = false
• string xdebug.gc_stats_output_dir = /tmp
• string xdebug.gc_stats_output_name = gcstats.%p

• xdebug_get_gc_run_count() : int
• xdebug_get_gc_total_collected_roots() : int
• xdebug_get_gcstats_filename() : mixed
• xdebug_start_gcstats() : mixed
• xdebug_stop_gcstats() : string

Settings

bool xdebug.gc_stats_enable = false #

Introduced in Xdebug >= 2.6

If this setting is enabled, then statistics for garbage collection runs are automatically collected into the given directory set with xdebug.gc_stats_output_dir and with an automatically generated name configured by xdebug.gc_stats_output_name.

string xdebug.gc_stats_output_dir = /tmp #

Introduced in Xdebug >= 2.6

string xdebug.gc_stats_output_name = gcstats.%p #

Introduced in Xdebug >= 2.6

This setting determines the name of the file that is used to dump garbage collection statistics into. The setting specifies the format with format specifiers, very similar to sprintf() and strftime(). There are several format specifiers that can be used to format the file name.

See the xdebug.trace_output_name documentation for the supported specifiers.

Functions

xdebug_get_gc_run_count() : int #

Returns the number of garbage collection runs that have been triggered so far

The function returns the number of times the garbage collection has been triggered in the currently running script.

This number is available even if the xdebug.gc_stats_enable INI setting is set to false.

xdebug_get_gc_total_collected_roots() : int #

Returns the number of variable roots that have been collected so far

The function returns the number of variable roots that the garbage collection has collected during all runs of the garbage collector in the current script.

This number is available even if the xdebug.gc_stats_enable INI setting is set to false.

xdebug_get_gcstats_filename() : mixed #

Returns the garbage collection statistics filename

Returns the name of the file which is used to save garbage collection information to, or false if statistics collection is not active.

xdebug_start_gcstats( ?string $gcstatsFile = null ) : mixed #

Start the collection of garbage collection statistics

Start tracing garbage collection attempts from this point to the file in the gcstatsFile parameter. If no filename is given, then garbage collection stats file will be placed in the directory as configured by the xdebug.gc_stats_output_dir setting.

In case a file name is given as first parameter, the name is relative to the current working directory. This current working directory might be different than you expect it to be, so please use an absolute path in case you specify a file name. Use the PHP function getcwd() to figure out what the current working directory is.

If xdebug.gc_stats_enable is enabled, then filename depends on the xdebug.gc_stats_output_name setting.

The full path and filename to which Xdebug collects statistics into is returned from this function. This will be either the filename you pass in, or the auto generated filename if no filename has been passed in.

xdebug_stop_gcstats() : string #

Stops the current garbage collection statistics collection

Stop garbage collection statistics collection and closes the output file.

The function returns the filename of the file where the statistics were written to.