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

Function Trace

Xdebug allows you to log all function calls, including parameters and return values to a file in different formats.

Those so-called "function traces" can be a help for when you are new to an application or when you are trying to figure out what exactly is going on when your application is running. The function traces can optionally also show the values of variables passed to the functions and methods, and also return values. In the default traces those two elements are not available.

Output Formats #

There are three output formats. One is meant as a human readable trace, another one is more suited for computer programs as it is easier to parse, and the last one uses HTML for formatting the trace. You can switch between the two different formats with the xdebug.trace_format setting. There are a few settings that control which information is written to the trace files. There are settings for including variable assignments (xdebug.collect_assignments) and for including return values (xdebug.collect_return) for example. The example below shows what effect the different settings have for the human readable function traces.

The Script

<?php
$str 
"Xdebug";
function 
ret_ord$c )
{
    return 
ord$c );
}

foreach ( 
str_split$str ) as $char )
{
    echo 
$char": "ret_ord$char ), "\n";
}
?>

The Results

A typical output without the xdebug.collect_return or xdebug.collect_assignments features turned on is the following trace:

TRACE START [2007-05-06 14:37:16]
    0.0003     114112   -> {main}() ../trace.php:0
    0.0004     114272     -> str_split('Xdebug') ../trace.php:8
    0.0007     117424     -> ret_ord($c = 'X') ../trace.php:10
    0.0007     117584       -> ord('X') ../trace.php:5
    0.0009     117584     -> ret_ord($c = 'd') ../trace.php:10
    0.0009     117584       -> ord('d') ../trace.php:5
    0.0010     117584     -> ret_ord($c = 'e') ../trace.php:10
    0.0011     117584       -> ord('e') ../trace.php:5
    0.0012     117584     -> ret_ord($c = 'b') ../trace.php:10
    0.0013     117584       -> ord('b') ../trace.php:5
    0.0014     117584     -> ret_ord($c = 'u') ../trace.php:10
    0.0014     117584       -> ord('u') ../trace.php:5
    0.0016     117584     -> ret_ord($c = 'g') ../trace.php:10
    0.0016     117584       -> ord('g') ../trace.php:5
    0.0019      41152
TRACE END   [2007-05-06 14:37:16]

There are a number of settings that affect the output of trace files.

To show the return values of all function and method calls, turn on the xdebug.collect_return and xdebug.collect_assignments settings.

TRACE START [2007-05-06 14:37:35]
    0.0003     114112   -> {main}() ../trace.php:0
    0.0004     114272     -> str_split('Xdebug') ../trace.php:8
                          >=> array (0 => 'X', 1 => 'd', 2 => 'e', 3 => 'b', 4 => 'u', 5 => 'g')
    0.0007     117424     -> ret_ord($c = 'X') ../trace.php:10
    0.0007     117584       -> ord('X') ../trace.php:5
                            >=> 88
                          >=> 88
    0.0009     117584     -> ret_ord($c = 'd') ../trace.php:10
    0.0009     117584       -> ord('d') ../trace.php:5
                            >=> 100
                          >=> 100
    0.0011     117584     -> ret_ord($c = 'e') ../trace.php:10
    0.0011     117584       -> ord('e') ../trace.php:5
                            >=> 101
                          >=> 101
    0.0013     117584     -> ret_ord($c = 'b') ../trace.php:10
    0.0013     117584       -> ord('b') ../trace.php:5
                            >=> 98
                          >=> 98
    0.0015     117584     -> ret_ord($c = 'u') ../trace.php:10
    0.0016     117584       -> ord('u') ../trace.php:5
                            >=> 117
                          >=> 117
    0.0017     117584     -> ret_ord($c = 'g') ../trace.php:10
    0.0018     117584       -> ord('g') ../trace.php:5
                            >=> 103
                          >=> 103
                        >=> 1
    0.0021      41152
TRACE END   [2007-05-06 14:37:35]

The default format is meant for consumption by humans. It is also possible to generate a tab separated trace by setting xdebug.trace_format to 1.

The Xdebug source distribution has a script that can be used to run some minimal analyses on these files.

Version: 3.0.3
TRACE START [2007-05-06 18:29:01]
1	0	0	0.010870	114112	{main}	1	../trace.php	0
2	1	0	0.032009	114272	str_split	0	../trace.php	8
2	1	1	0.032073	116632
2	2	0	0.033505	117424	ret_ord	1	../trace.php	10
3	3	0	0.033531	117584	ord	0	../trace.php	5
3	3	1	0.033551	117584
2	2	1	0.033567	117584
2	4	0	0.033718	117584	ret_ord	1	../trace.php	10
3	5	0	0.033740	117584	ord	0	../trace.php	5
3	5	1	0.033758	117584
2	4	1	0.033770	117584
2	6	0	0.033914	117584	ret_ord	1	../trace.php	10
3	7	0	0.033936	117584	ord	0	../trace.php	5
3	7	1	0.033953	117584
2	6	1	0.033965	117584
2	8	0	0.034108	117584	ret_ord	1	../trace.php	10
3	9	0	0.034130	117584	ord	0	../trace.php	5
3	9	1	0.034147	117584
2	8	1	0.034160	117584
2	10	0	0.034302	117584	ret_ord	1	../trace.php	10
3	11	0	0.034325	117584	ord	0	../trace.php	5
3	11	1	0.034342	117584
2	10	1	0.034354	117584
2	12	0	0.034497	117584	ret_ord	1	../trace.php	10
3	13	0	0.034519	117584	ord	0	../trace.php	5
3	13	1	0.034536	117584
2	12	1	0.034549	117584
1	0	1	0.034636	117584
TRACE END   [2007-05-06 18:29:01]

VIM syntax file #

Xdebug ships with a VIM syntax file that syntax highlights the trace files: xt.vim. In order to make VIM recognise this new format you need to perform the following steps:

  1. Copy the xt.vim file to ~/.vim/syntax
  2. Edit, or create, ~/.vim/filetype.vim and add the following lines:
    augroup filetypedetect
    au BufNewFile,BufRead *.xt  setf xt
    augroup END
    

With those settings made an opened trace file looks like:

TRACE START [2007-05-15 20:06:02]
    0.0003     115208   -> {main}() ../trace.php:0
    0.0004     115368     -> str_split() ../trace.php:8
    0.0006     118520     -> ret_ord() ../trace.php:10
    0.0007     118680       -> ord() ../trace.php:5
    0.0008     118680     -> ret_ord() ../trace.php:10
    0.0009     118680       -> ord() ../trace.php:5
    0.0010     118680     -> ret_ord() ../trace.php:10
    0.0010     118680       -> ord() ../trace.php:5
    0.0012     118680     -> ret_ord() ../trace.php:10
    0.0012     118680       -> ord() ../trace.php:5
    0.0014     118680     -> ret_ord() ../trace.php:10
    0.0014     118680       -> ord() ../trace.php:5
    0.0016     118680     -> ret_ord() ../trace.php:10
    0.0016     118680       -> ord() ../trace.php:5
    0.0019      54880
TRACE END   [2007-05-15 20:06:02]

Folding also sorta works so you can use zc and zo to fold away parts of the trace files.

Related Settings and Functions

Settings


boolean xdebug.collect_assignments = false #

This setting, defaulting to 0, controls whether Xdebug should add variable assignments to function traces. Assign-by-var (=&) assignments are included too.


boolean xdebug.collect_return = false #

This setting, defaulting to 0, controls whether Xdebug should write the return value of function calls to the trace files.


string xdebug.log = #

Configures Xdebug's log file.

Xdebug will log to this file all file creations issues, Step Debugging connection attempts, failures, and debug communication.

Enable this functionality by setting the value to a absolute path. Make sure that the system user that PHP runs at (such as www-data if you are running with Apache) can create and write to the file.

The file is opened in append-mode, and will therefore not be overwritten by default. There is no concurrency protection available.

The log file will include any attempt that Xdebug makes to connect to an IDE:

[2693358] Log opened at 2020-09-02 07:19:09.616195
[2693358] [Step Debug] INFO: Connecting to configured address/port: localhost:9003.
[2693358] [Step Debug] ERR: Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port) :-(
[2693358] [Profiler] ERR: File '/foo/cachegrind.out.2693358' could not be opened.
[2693358] [Profiler] WARN: /foo: No such file or directory
[2693358] [Tracing] ERR: File '/foo/trace.1485761369' could not be opened.
[2693358] [Tracing] WARN: /foo: No such file or directory
[2693358] Log closed at 2020-09-02 07:19:09.617510

It includes the opening time (2020-09-02 07:19:09.616195), the IP/Hostname and port Xdebug is trying to connect to (localhost:9003), and whether it succeeded (Connected to client :-)). The number in brackets ([2693358]) is the Process ID.

It includes:

[2693358]
process ID in brackets
2020-09-02 07:19:09.616195
opening time

For Step Debugging:

INFO: Connecting to configured address/port: localhost:9003.
ERR: Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port) :-(

For Profiling:

ERR: File '/foo/cachegrind.out.2693358' could not be opened.
WARN: /foo: No such file or directory

For Function Trace:

ERR: File '/foo/trace.1485761369' could not be opened.
WARN: /foo: No such file or directory

All warnings and errors are described on the Description of errors page, with detailed instructions on how to resolve the problem, if possible. All errors are always logged through PHP's internal logging mechanism (configured with error_log in php.ini). All warnings and errors also show up in the diagnostics log that you can view by calling xdebug_info().

Step Debugger Communication

The debugging log can also log the communication between Xdebug and an IDE. This communication is in XML, and starts with the <init XML element:

<init
    xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
    fileuri="file:///home/httpd/www.xdebug.org/html/router.php"
    language="PHP" xdebug:language_version="7.4.11-dev"
    protocol_version="1.0" appid="2693358" idekey="XDEBUG_ECLIPSE">
        <engine version="3.0.0-dev"><![CDATA[Xdebug]]></engine>
        <author><![CDATA[Derick Rethans]]></author>
        <url><![CDATA[https://xdebug.org]]></url>
        <copyright><![CDATA[Copyright (c) 2002-2020 by Derick Rethans]]></copyright>
</init>

The fileuri attribute lists the entry point of your application, which can be useful to compare to breakpoint_set commands to see if path mappings are set-up correctly.

Beyond the <init element, you will find the configuration of features:

<- feature_set -i 4 -n extended_properties -v 1
-> <response
       xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
       command="feature_set" transaction_id="4" feature="extended_properties" success="1">
   </response>

And continuation commands:

<- step_into -i 9
-> <response
       xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
       command="step_into" transaction_id="9"
       status="break" reason="ok">
           <xdebug:message filename="file:///home/httpd/www.xdebug.org/html/router.php" lineno="3">
           </xdebug:message>
   </response>

You can read about DBGP - A common debugger protocol specification at its dedicated documation page.

The xdebug.log_level setting controls how much information is logged.

Note: Many Linux distributions now use systemd, which implements private tmp directories. This means that when PHP is run through a web server or as PHP-FPM, the /tmp directory is prefixed with something akin to:

/tmp/systemd-private-ea3cfa882b4e478993e1994033fc5feb-apache.service-FfWZRg

This setting can additionally be configured through the XDEBUG_CONFIG environment variable.


integer xdebug.log_level = 7 #

Configures which logging messages should be added to the log file.

The log file is configured with the xdebug.log setting.

The following levels are supported:

LevelNameExample
0CriticalsErrors in the configuration
1ErrorsConnection errors
3WarningsConnection warnings
5CommunicationProtocol messages
7InformationInformation while connecting
10DebugBreakpoint resolving information

Criticals, errors, and warnings always show up in the diagnostics log that you can view by calling xdebug_info().

Criticals and errors are additionally logged through PHP's internal logging mechanism (configured with error_log in php.ini).

This setting can additionally be configured through the XDEBUG_CONFIG environment variable.


string xdebug.mode = develop #

This setting controls which Xdebug features are enabled.

This setting can only be set in php.ini or files like 99-xdebug.ini that are read when a PHP process starts (directly, or through php-fpm), but not in .htaccess and .user.ini files, which are read per-request.

The following values are accepted:

off
Nothing is enabled. Xdebug does no work besides checking whether functionality is enabled. Use this setting if you want close to 0 overhead.
develop
Enables Development Aids including the overloaded var_dump().
coverage
Enables Code Coverage Analysis to generate code coverage reports, mainly in combination with PHPUnit.
debug
Enables Step Debugging. This can be used to step through your code while it is running, and analyse values of variables.
gcstats
Enables Garbage Collection Statistics to collect statistics about PHP's Garbage Collection Mechanism.
profile
Enables Profiling, with which you can analyse performance bottlenecks with tools like KCacheGrind.
trace
Enables the Function Trace feature, which allows you record every function call, including arguments, variable assignment, and return value that is made during a request to a file.

You can enable multiple modes at the same time by comma separating their identifiers as value to xdebug.mode: xdebug.mode=develop,trace.

You can also set the mode by setting the XDEBUG_MODE environment variable on the command-line; this will take precedence over the xdebug.mode setting, but will no change the value of the xdebug.mode setting.


string xdebug.output_dir = /tmp #

The directory where Xdebug will write tracing, profiling, and garbage collection statistics to. This directory needs to be writable for the system user with which PHP is running.

This setting can be changed in php.ini, .htaccess (and equivalent files), and within a PHP file with ini_set().

In some cases (when profiling, or when xdebug.start_with_request=yes with tracing), Xdebug creates the file before the script runs. In that case, changes made through ini_set() will not be taken into account.

This setting can additionally be configured through the XDEBUG_CONFIG environment variable.


string xdebug.start_with_request = default #

A Function Trace, Garbage Collection Statistics, Profiling, or Step Debugging can be activated at the start of a PHP request. Whether this happens depends on the value of this setting:

yes

The functionality starts when the PHP request starts, and before any PHP code is run.

For example xdebug.mode=trace and xdebug.start_with_request=yes starts a Function Trace for the whole request.

no

The functionality does not get activated when the request starts.

You can still start a Function Trace with xdebug_start_trace(), Step Debugging with xdebug_break(), or Garbage Collection Statistics with xdebug_start_gcstats().

trigger

The functionality only gets activated when a specific trigger is present when the request starts.

The name of the trigger is XDEBUG_TRIGGER, and Xdebug checks for its presence in either $_ENV (environment variable), $_GET or $_POST variable, or $_COOKIE (HTTP cookie name).

There is also a legacy fallback to a functionality specific trigger name: XDEBUG_PROFILE (for Profiling), XDEBUG_TRACE (for a Function Trace), and XDEBUG_SESSION (for Step Debugging).

Debug session management for Step Debugging is also available through XDEBUG_SESSION_START.

With xdebug.trigger_value you can control which specific trigger value will activate the trigger. If xdebug.trigger_value is set to an empty string, any value will be accepted.

default

The default value depends on xdebug.mode:

  • debug: trigger

  • gcstats: no

  • profile: yes

  • trace: trigger


integer xdebug.trace_format = 0 #

The format of the trace file.

ValueDescription
0shows a human readable indented trace file with: time index, memory usage, memory delta, level, function name, function parameters, filename and line number.
1writes a computer readable format which has two different records. There are different records for entering a stack frame, and leaving a stack frame. The table below lists the fields in each type of record. Fields are tab separated.
2writes a trace formatted in (simple) HTML.

Fields for the computerized format:

Record type123456789101112 - ...
Entry level function # always '0' time index memory usage function name user-defined (1) or internal function (0) name of the include or require file filename line number no. of arguments arguments (as many as specified in field 11) - tab separated
Exit level function # always '1' time index memory usage empty
Return level function # always 'R' empty return value empty

See the introduction for Function Trace for a few examples.


integer xdebug.trace_options = 0 #

When set to '1' the trace files will be appended to, instead of being overwritten in subsequent requests.


string xdebug.trace_output_name = trace.%c #

This setting determines the name of the file that is used to dump traces 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. The '.xt' extension is always added automatically.

The possible format specifiers are:

SpecifierMeaningExample FormatExample Filename
%ccrc32 of the current working directorytrace.%ctrace.1258863198.xt
%ppidtrace.%ptrace.5174.xt
%rrandom numbertrace.%rtrace.072db0.xt
%s

script name 2

cachegrind.out.%scachegrind.out._home_httpd_html_test_xdebug_test_php
%ttimestamp (seconds)trace.%ttrace.1179434742.xt
%utimestamp (microseconds)trace.%utrace.1179434749_642382.xt
%H$_SERVER['HTTP_HOST']trace.%Htrace.kossu.xt
%R$_SERVER['REQUEST_URI']trace.%Rtrace._test_xdebug_test_php_var=1_var2=2.xt
%U$_SERVER['UNIQUE_ID'] 3trace.%Utrace.TRX4n38AAAEAAB9gBFkAAAAB.xt
%Ssession_id (from $_COOKIE if set)trace.%Strace.c70c1ec2375af58f74b390bbdd2a679d.xt
%%literal %trace.%%trace.%%.xt

2 This one is only available for trace file names since Xdebug 2.6.

3 New in version 2.2. This one is set by Apache's mod_unique_id module


string xdebug.trigger_value = "" #

This setting can be used when xdebug.start_with_request is set to trigger, which is the default for Step Debugging and Function Trace.

In trigger mode, Xdebug will only start its functionality when the XDEBUG_TRIGGER is set in the environment, or when the XDEBUG_TRIGGER GET, POST, or COOKIE variable is set.

The legacy names XDEBUG_SESSION (for Step Debugging), XDEBUG_PROFILE (for Profiling), and XDEBUG_TRACE (for Function Trace) can also be used instead of XDEBUG_TRIGGER.

Normally, Xdebug does not look at which value is actually used. If this setting is set to a non-empty string, then Xdebug will only trigger if the value matches the value of this setting.

With the following settings:

xdebug.mode=profile
xdebug.start_with_request=trigger
xdebug.trigger_value=StartProfileForMe

Xdebug's profiler will only start when either the environment variable XDEBUG_TRIGGER is set to StartProfileForMe, the GET or POST variable XDEBUG_TRIGGER is set to StartProfileForMe, or when the cookie XDEBUG_TRIGGER has the value StartProfileForMe.

See also:

xdebug.start_with_request#trigger
For how the triggering mechanism works, and which environment and server variables Xdebug acts on.

integer xdebug.var_display_max_children = 128 #

Controls the amount of array children and object's properties are shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or when making a Function Trace.

To disable any limitation, use -1 as value.

This setting does not have any influence on the number of children that is send to the client through the Step Debugging feature.


integer xdebug.var_display_max_data = 512 #

Controls the maximum string length that is shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or when making a Function Trace.

To disable any limitation, use -1 as value.

This setting does not have any influence on the number of children that is send to the client through the Step Debugging feature.


integer xdebug.var_display_max_depth = 3 #

Controls how many nested levels of array elements and object properties are when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or when making a Function Trace.

The maximum value you can select is 1023. You can also use -1 as value to select this maximum number.

This setting does not have any influence on the number of children that is send to the client through the Step Debugging feature.

Setting the value to a high number could potentially result in PHP using up all the available memory, so use with caution.

Functions


xdebug_get_tracefile_name() : mixed #

Returns the name of the function trace file

Returns the name of the file which is used to trace the output of this script to, or null if tracing is not active. This is useful when the trace was started automatically because xdebug.start_with_request was set to yes.


xdebug_info() : void #

Show diagnostic information

This function returns an HTML page which shows diagnostic information. It is analogous to PHP's phpinfo() function.

The HTML output includes which mode is active, what the settings are, and diagnostic information in case there are problems with debugging connections, opening of files, etc.

Each warning and error in the diagnostics log also links through to the Description of errors documentation page.


xdebug_start_trace( ?string $traceFile = null, int $options = 0 ) : ?string #

Starts a new function trace

Start tracing function calls from this point to the file in the $trace_file parameter. If no filename is given, then the trace file will be placed in the directory as configured by the xdebug.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.

The name of the trace file is {$trace_file}.xt. If the trace was started at the beginning of the request because xdebug.start_with_request is set to yes, then the filename depends on the xdebug.trace_output_name setting.

The options parameter is a bitfield; currently there are three options:

The options parameter is a bitfield; currently there are three options:

XDEBUG_TRACE_APPEND (1)
makes the trace file open in append mode rather than overwrite mode
XDEBUG_TRACE_COMPUTERIZED (2)
creates a trace file with the format as described under 1 "xdebug.trace_format".
XDEBUG_TRACE_HTML (4)
creates a trace file as an HTML table
XDEBUG_TRACE_NAKED_FILENAME (8)
Normally, Xdebug always adds ".xt" to the end of the filename that you pass in as first argument to this function. With the XDEBUG_TRACE_NAKED_FILENAME flag set, ".xt" is not added.

The settings xdebug.collect_assignments and xdebug.collect_return influence what information is logged to the trace file and the setting xdebug.trace_format influences the format of the trace file.

The full path and filename to which Xdebug traces is returned from this function. This will be either the filename you pass in (potentially with ".xt" added), or the auto generated filename if no filename has been passed in.


xdebug_stop_trace() : false|string #

Stops the current function trace

Stop tracing function calls and closes the trace file.

The function returns the filename of the file where the trace was written to.