If you find Xdebug useful, please consider supporting the project.

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. 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.

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().

Tabular Text (Human Readable)

The default (and only for now) 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:

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

Related 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

The directory where the garbage collection statistics output will be written to, make sure that the user who the PHP will be running as has write permissions to that directory. This setting can not be set in your script with ini_set().

string xdebug.gc_stats_output_name = gcstats.%p

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.

Related Functions


xdebug_get_gc_run_count() : int

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

Introduced in version 2.6

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.

Introduced in version 2.6

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() : string

Returns the garbage collection statistics filename

Introduced in version 2.6

Returns the name of the file which is used to save garbage collection information to.


xdebug_start_gcstats( [ string $gcstats_file ] ) : string

Start the collection of garbage collection statistics

Introduced in version 2.6

Start tracing garbage collection attempts from this point to the file in the gcstats_file 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

Introduced in version 2.6

Stop garbage collection statistics collection and closes the output file.

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