>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 variables (xdebug.collect_params) 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
Below are the results with different settings of the xdebug.collect_params setting. As this is not a web environment the value of 2 does not have any meaning as tool tips don't work in text files.
```
default
collect_params=1
collect_params=3
collect_params=4
TRACE START [2007-05-06 14:37:06]
0.0003 114112 -> {main}() ../trace.php:0
0.0004 114272 -> str_split() ../trace.php:8
0.0153 117424 -> ret_ord() ../trace.php:10
0.0165 117584 -> ord() ../trace.php:5
0.0166 117584 -> ret_ord() ../trace.php:10
0.0167 117584 -> ord() ../trace.php:5
0.0168 117584 -> ret_ord() ../trace.php:10
0.0168 117584 -> ord() ../trace.php:5
0.0170 117584 -> ret_ord() ../trace.php:10
0.0170 117584 -> ord() ../trace.php:5
0.0172 117584 -> ret_ord() ../trace.php:10
0.0172 117584 -> ord() ../trace.php:5
0.0173 117584 -> ret_ord() ../trace.php:10
0.0174 117584 -> ord() ../trace.php:5
0.0177 41152
TRACE END [2007-05-06 14:37:07]
TRACE START [2007-05-06 14:37:13]
0.0003 114112 -> {main}() ../trace.php:0
0.0004 114272 -> str_split('Xdebug') ../trace.php:8
0.0007 117424 -> ret_ord('X') ../trace.php:10
0.0007 117584 -> ord('X') ../trace.php:5
0.0009 117584 -> ret_ord('d') ../trace.php:10
0.0009 117584 -> ord('d') ../trace.php:5
0.0010 117584 -> ret_ord('e') ../trace.php:10
0.0011 117584 -> ord('e') ../trace.php:5
0.0012 117584 -> ret_ord('b') ../trace.php:10
0.0013 117584 -> ord('b') ../trace.php:5
0.0014 117584 -> ret_ord('u') ../trace.php:10
0.0014 117584 -> ord('u') ../trace.php:5
0.0016 117584 -> ret_ord('g') ../trace.php:10
0.0016 117584 -> ord('g') ../trace.php:5
0.0019 41152
TRACE END [2007-05-06 14:37:13]
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]
```
Besides the xdebug.collect_params settings there is another number of settings that affect the output of trace files. The first tab "default" shows the same as the default as above. The second tab "show_mem_delta=1" also shows the memory usage difference between two different lines in the output file.
On the "collect_return=1" tab the return values of all the function calls are also visible. This you turn on with the xdebug.collect_return setting.
The tab called "collect_assignments=1" shows variable assigments, which can be turned on with the xdebug.collect_assignments setting.
The last tab shows a different output format that is much easier to parse, but harder to read. The xdebug.trace_format setting is therefore mostly useful if there is an additional tool to interpret the trace files.
```
default
show_mem_delta=1
collect_return=1
trace_format=1
TRACE START [2007-05-06 14:37:06]
0.0003 114112 -> {main}() ../trace.php:0
0.0004 114272 -> str_split() ../trace.php:8
0.0153 117424 -> ret_ord() ../trace.php:10
0.0165 117584 -> ord() ../trace.php:5
0.0166 117584 -> ret_ord() ../trace.php:10
0.0167 117584 -> ord() ../trace.php:5
0.0168 117584 -> ret_ord() ../trace.php:10
0.0168 117584 -> ord() ../trace.php:5
0.0170 117584 -> ret_ord() ../trace.php:10
0.0170 117584 -> ord() ../trace.php:5
0.0172 117584 -> ret_ord() ../trace.php:10
0.0172 117584 -> ord() ../trace.php:5
0.0173 117584 -> ret_ord() ../trace.php:10
0.0174 117584 -> ord() ../trace.php:5
0.0177 41152
TRACE END [2007-05-06 14:37:07]
```
##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
**xdebug.auto_trace**
Type: _boolean, Default value: 0_
When this setting is set to on, the tracing of function calls will be enabled just before the script is run. This makes it possible to trace code in the [auto_prepend_file](http://www.php.net/manual/en/configuration.directives.php#ini.auto-prepend-file).
**xdebug.collect_assignments**
Type: _boolean, Default value: 0, Introduced in Xdebug > 2.1_
This setting, defaulting to 0, controls whether Xdebug should add variable assignments to function traces.
**xdebug.collect_includes**
Type: _boolean, Default value: 1_
This setting, defaulting to 1, controls whether Xdebug should write the filename used in include(), include_once(), require() or require_once() to the trace files.
**xdebug.collect_params**
Type: _integer, Default value: 0_
This setting, defaulting to 0, controls whether Xdebug should collect the parameters passed to functions when a function call is recorded in either the function trace or the stack trace.
The setting defaults to 0 because for very large scripts it may use huge amounts of memory and therefore make it impossible for the huge script to run. You can most safely turn this setting on, but you can expect some problems in scripts with a lot of function calls and/or huge data structures as parameters. Xdebug 2 will not have this problem with increased memory usage, as it will never store this information in memory. Instead it will only be written to disk. This means that you need to have a look at the disk usage though.
This setting can have four different values. For each of the values a different amount of information is shown. Below you will see what information each of the values provides. See also the introduction of the feature Stack Traces for a few screenshots.
|Value |Argument Information Shown|
|=|=|
|0 |None.|
|1 |Type and number of elements (f.e. string(6), array(8)).|
|2 |Type and number of elements, with a tool tip for the full information 1.|
|3 |Full variable contents (with the limits respected as set by xdebug.var_display_max_children, xdebug.var_display_max_data and xdebug.var_display_max_depth.|
|4 |Full variable contents and variable name.|
|5 |PHP serialized variable contents, without the name. (New in Xdebug 2.3)|
1 in the CLI version of PHP it will not have the tool tip, nor in output files.
**xdebug.collect_return**
Type: _boolean, Default value: 0_
This setting, defaulting to 0, controls whether Xdebug should write the return value of function calls to the trace files.
For computerized trace files (xdebug.trace_format=1) this only works from Xdebug 2.3 onwards.
**xdebug.show_mem_delta**
Type: _integer, Default value: 0_
When this setting is set to something != 0 Xdebug's human-readable generated trace files will show the difference in memory usage between function calls. If Xdebug is configured to generate computer-readable trace files then they will always show this information.
**xdebug.trace_enable_trigger**
Type: _boolean, Default value: 0, Introduced in Xdebug > 2.2_
When this setting is set to 1, you can trigger the generation of trace files by using the XDEBUG_TRACE GET/POST parameter, or set a cookie with the name XDEBUG_TRACE. This will then write the trace data to defined directory. In order to prevent Xdebug to generate trace files for each request, you need to set xdebug.auto_trace to 0. Access to the trigger itself can be configured through xdebug.trace_enable_trigger_value.
**xdebug.trace_enable_trigger_value**
Type: _string, Default value: "", Introduced in Xdebug > 2.3_
This setting can be used to restrict who can make use of the XDEBUG_TRACE functionality as outlined in xdebug.trace_enable_trigger. When changed from its default value of an empty string, the value of the cookie, GET or POST argument needs to match the shared secret set with this setting in order for the trace file to be generated.
**xdebug.trace_format**
Type: _integer, Default value: 0_
The format of the trace file.
|Value |Description|
|=|=|
|0 |shows a human readable indented trace file with: time index, memory usage, memory delta (if the setting xdebug.show_mem_delta is enabled), level, function name, function parameters (if the setting xdebug.collect_params is enabled), filename and line number.|
|1 |writes 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.|
|2 |writes a trace formatted in (simple) HTML.|
Fields for the computerized format:
|Record type |1 |2 |3 |4 |5 |6 |7 |8 |9 |10 |11 |12 - ...|
|=|=|=|=|=|=|=|=|=|=|=|=|
|Entry |level |function # |always '0' |time index |memory usage| function name| user-defined (1) or internal function (0) |name of the include/require file |filename| line number |no. of parameters |parameters (as many as specified in field 11) - tab separated|
|Exit |level| function # |always '1'| time index| memory usage|empty|empty|empty|empty|empty|empty|empty |
|Return |level| function # |always 'R'|empty|empty | return value| empty|empty|empty|empty|empty|empty|
See the introduction of Function Traces for a few examples.
**xdebug.trace_options**
Type: _integer, Default value: 0_
When set to '1' the trace files will be appended to, instead of being overwritten in subsequent requests.
**xdebug.trace_output_dir**
Type: _string, Default value: /tmp_
The directory where the tracing files will be written to, make sure that the user who the PHP will be running as has write permissions to that directory.
**xdebug.trace_output_name**
Type: _string, Default value: 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:
|Specifier |Meaning |Example Format |Example Filename|
|=|=|=|=|
|%c| crc32 of the current working directory |trace.%c |trace.1258863198.xt|
|%p |pid| trace.%p |trace.5174.xt|
|%r |random number| trace.%r |trace.072db0.xt|
|%s |script name 2|cachegrind.out.%s| cachegrind.out._home_httpd_html_test_xdebug_test_php|
|%t |timestamp (seconds) |trace.%t| trace.1179434742.xt|
|%u |timestamp (microseconds)| trace.%u |trace.1179434749_642382.xt|
|%H |$_SERVER['HTTP_HOST']| trace.%H |trace.kossu.xt|
|%R |$_SERVER['REQUEST_URI'] |trace.%R |trace._test_xdebug_test_php_var=1_var2=2.xt|
|%U |$_SERVER['UNIQUE_ID'] 3| trace.%U |trace.TRX4n38AAAEAAB9gBFkAAAAB.xt|
|%S |session_id (from $_COOKIE if set)| trace.%S| trace.c70c1ec2375af58f74b390bbdd2a679d.xt|
|%% |literal %| trace.%% |trace.%%.xt|
2 This one is not available for trace file names.
3 New in version 2.2. This one is set by Apache's mod_unique_id module
**xdebug.var_display_max_children**
Type: _integer, Default value: 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 through Function Traces.
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 Remote Debugging feature.
**xdebug.var_display_max_data**
Type: _integer, Default value: 512_
Controls the maximum string length that is shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or through Function Traces.
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 Remote Debugging feature.
**xdebug.var_display_max_depth**
Type: _integer, Default value: 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 through Function Traces.
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 Remote Debugging feature.
##Related Functions
**string xdebug_get_tracefile_name()**
_Returns the name of the function trace file_
Returns the name of the file which is used to trace the output of this script too. This is useful when xdebug.auto_trace is enabled.
**void xdebug_start_trace( string trace_file [, integer options] )**
_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.trace_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 xdebug.auto_trace is enabled, then the format of the filename is "{filename}.xt" where the "{filename}" part depends on the xdebug.trace_output_name setting. 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. (New in Xdebug 2.3).
Unlike Xdebug 1, Xdebug 2 will not store function calls in memory, but always only write to disk to relieve the pressure on used memory. The settings xdebug.collect_includes, xdebug.collect_params 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.
**void xdebug_stop_trace()**
Stops the current function trace
Stop tracing function calls and closes the trace file.
