Xdebug文档(四)函数跟踪

时间:2022-06-05 10:03:18

Xdebug能让你把所有函数调用,包括参数和返回值以不同的格式记录到文件中。

这些号称“函数跟踪”功能能帮助你面对一个新应用程序,亦或者在程序运行时你想弄清楚它在做什么。函数跟踪功能可以选择性地显示函数或方法传递的变量值,也可以是返回值。跟踪这两个元素默认情况下不开启的。

输出格式

共有三种输出格式。一种是人类可读性跟踪信息,另一个是更适合计算机程序解析的,最后一种使用HTML格式化跟踪信息的。你可以使用xdebug_trace_format设置切换这两种不周的格式。还有一些设置是控制哪些信息写入跟踪文件的。例如设置包含变量的(xdebug.collect_params)和包含返回值的(xdebug.collect_return)。以下例子展示人类可读性的函数跟踪信息的不同设置效果:

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

以下由xdebug.collect_params设置不同值时的结果。当不在web环境下,2值不包含鼠标提示。

默认值:

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]

Collect_params=1:

TRACE START [2007-05-06 14:37:11]
    0.0003     114112   -> {main}() ../trace.php:0
    0.0004     114272     -> str_split(string(6)) ../trace.php:8
    0.0007     117424     -> ret_ord(string(1)) ../trace.php:10
    0.0007     117584       -> ord(string(1)) ../trace.php:5
    0.0009     117584     -> ret_ord(string(1)) ../trace.php:10
    0.0009     117584       -> ord(string(1)) ../trace.php:5
    0.0010     117584     -> ret_ord(string(1)) ../trace.php:10
    0.0011     117584       -> ord(string(1)) ../trace.php:5
    0.0012     117584     -> ret_ord(string(1)) ../trace.php:10
    0.0013     117584       -> ord(string(1)) ../trace.php:5
    0.0014     117584     -> ret_ord(string(1)) ../trace.php:10
    0.0014     117584       -> ord(string(1)) ../trace.php:5
    0.0016     117584     -> ret_ord(string(1)) ../trace.php:10
    0.0016     117584       -> ord(string(1)) ../trace.php:5
    0.0019      41152
TRACE END   [2007-05-06 14:37:11]

Collect_params=3:

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]

Collect_params=4:

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]

除了xdebug.collet_params设置还有另一些设置影响跟踪文件的输出效果。“show_mem_delta=1”可以显示内存使用量在两个不同列中。

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

“collect_return=1”显示被调用函数的返回值:

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]

“collect_assignments=1”显示变量赋予,详见xdebug.collect_assignments设置。

“xdebug.trace_format”设置改变输出格式让解析更容易但反而让人更难理解。这对于用第三方工具解析跟踪文件最有用处。

Version: 2.0.0RC4-dev
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 语法文件

Xdebug 携带一个VIM语法文件能对跟踪文件的语法提亮,该语法文件名:xt.vim。 为了使VIM识别新格式,你需这么做:

  1. 复制xt.vim文件到 ~/.vim/syntax
  2. 编辑或创建 ~/.vim/filetype.vim 文件,并添加以下代码:
augroup filetypedetect
au BufNewFile,BufRead *.xt  setf xt
augroup END

做完这些后,打开的跟踪文件就会类似这样:

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]

相关设置:

xdebug.auto_trace

类型: boolean, 默认值: 0

打开此设置时,脚本在运行前函数调用追踪将开启。这将可能追踪auto_prepend_file设置的代码文件。

xdebug.collect_assignments

类型: boolean, 默认值: 0, 始于 Xdebug > 2.1

用于控制xdebug是否添加变量赋予到函数追踪当中。

xdebug.collect_includes

类型: boolean, 默认值: 1

用于控制xdebug是否将include(), include_once(), require() 或 require_once() 引用的文件名写入到跟踪文件中。

xdebug.collect_params

类型: integer, 默认值: 0

默认为0时,该设置控制xdebug不管是函数追踪还是堆栈跟踪都会收集调用函数的参数。

默认0值是考虑到大规模脚本会占用大量内存,所以不会为了大脚本来运行它。你可以安全地打开此设置,但你会预料到会一些脚本上的问题像大量函数调用兼庞大的数据结构作为参数传递。Xdebug2不会有增加内存使用的问题,因为它不会存储到内存,而是只存入磁盘中。这只需要你有足够的磁盘使用量即可。

该设置有4种设置值。每种都会呈现不同的信息。以下表格展示各种设置值信息:

Value

Argument   Information   Shown

0

无.

1

展示变量元素的值类型和值。

2

展示变量元素的值类型和值,并附带滑鼠提示显示完整信息。(CLI模式下不存在滑鼠提示)

3

完整变量内容(内容受限于以下设置: xdebug.var_display_max_children,xdebug.var_display_max_data and xdebug.var_display_max_depth.)

4

完整变量内容和名称。

5

PHP   序列化变量内容,不含名称。(2.3版本新特性)

 

xdebug.collect_return

类型: boolean, 默认值: 0

控制是否将函数调用的返回值写入到跟踪文件里。

要达到计算机化跟踪文件(xdebug.trace_format=1) 必须要用到Xdebug 2.3 以上版本。

xdebug.show_mem_delta

类型: integer, 默认值: 0

当此设置不为0值,可人为读取的跟踪文件将各函数调用占用内存量的不同。如果xdebug设置为产生计算机可读的跟踪文件,则他们会一直显示这样的信息。

xdebug.trace_enable_trigger

类型: boolean, 默认值: 0, 始于 Xdebug > 2.2

设置为1时,你能使用XDEBUG_TRACE GET/POST 参数或设置一名为XDEBUG_TRACE的cookie值触发跟踪文件的产生。跟踪数据文件将写入到预定义文件夹内。为了防止xdebug在每次请求时产生跟踪文件,你需要将xdebug.auto_trace设为0。访问触发器自身可通过设置 xdebug.trace_enable_trigger_value

xdebug.trace_enable_trigger_value

类型: string, 默认值: "", 始于 Xdebug > 2.3

该设置用于限制谁能利用XDEBUG_TRACE功能描述到xdebug.trace_enable_trigger。当变更了默认空值后,cookie,GET或POST值需要为跟踪文件的产生匹配设置内的共享隐藏设置。

xdebug.trace_format

类型: integer, 默认值: 0

跟踪文件的格式。

描述

0

显示人类可读性排版式文件:时间点,内存量,内存增量(如果xdebug.show_mem_delta 开启), 层级, 函数名, 函数参数 (如果 xdebug.collect_params 开启),文件名和行号。

1

用两种不同记录编写记算机可读格式文件。其记录不同在于一个插入堆栈边框,一个移除堆栈边框。以下表格列出记录中每个栏位区别。

2

使用HTML写成跟踪文件。

计算机化格式的栏位:

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

Return

level

function #

always 'R'

empty

return value

empty

xdebug.trace_options

类型: integer, 默认值: 0

设为1时跟踪文件会后续添加内容,而不是在后续请求中直接覆盖。

xdebug.trace_output_dir

类型: string, 默认值: /tmp

跟踪文件写入路径,确保用户在运行PHP时有对该目录的写入权限。

xdebug.trace_output_name

类型: string, 默认值: trace.%c

该设置决定了跟踪信息写入的文件名。该设置使用了格式化标识符,类似于sprintf() 和 strftime()。 以几种格式标识符可以用于格式化文件名。后缀名 '.xt' 会自动地添加到文件名后。

格式化标识符列表:

标识符

意义

格式范例

文件范例

%c

当前工作路径的crc32效验值

trace.%c

trace.1258863198.xt

%p

进程标识符

trace.%p

trace.5174.xt

%r

随机数

trace.%r

trace.072db0.xt

%s

脚本名 2

cachegrind.out.%s

cachegrind.out._home_httpd_html_test_xdebug_test_php

%t

时间截 (秒)

trace.%t

trace.1179434742.xt

%u

时间截 (微秒)

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   (来源$_COOKIE,如果有设置)

trace.%S

trace.c70c1ec2375af58f74b390bbdd2a679d.xt

%%

literal %

trace.%%

trace.%%.xt

2 对于跟踪文件名这是不可用的。

3 版本2.2新特性。该特性由Apache mod_unique_id module 设置。

xdebug.var_display_max_children

类型: integer, 默认值: 128

在使用 xdebug_var_dump(),xdebug.show_local_vars 或 追踪函数时,该设置控制数组元素和对象属性的数量显示。

若不受限制,可以设为-1值。

该设置不受Remot_Debuggin远程调试的任何影响。

xdebug.var_display_max_data

类型: integer, 默认值: 512

在使用 xdebug_var_dump(),xdebug.show_local_vars 或 追踪函数时,该设置控制字符串长度显示最大值。

若不受限制,可以设为-1值。

该设置不受Remot_Debugging远程调试的任何影响。

xdebug.var_display_max_depth

类型: integer, 默认值: 3

在使用 xdebug_var_dump(),xdebug.show_local_vars 或 追踪函数时,该设置控制数组元素和对象属性的显示层级。

最大值为1023,你可以设为-1表示其最大值。

该设置不受Remot_Debugging远程调试的任何影响。

相关函数:

string xdebug_get_tracefile_name()

返回当前跟踪输出的脚本文件名。当xdebug.auto_trace打开时这个函数就能使用了。

void xdebug_start_trace( string trace_file [, integer options] )

启动一新的函数跟踪

位于某个点开始函数跟踪并入到参数trace_file指定的文件中。如果没有指定文件名,则跟踪文件存入 xdebug.trace_output_dir设定指定目录中。一旦在第一参数中指定了文件名,则该名称相对于当前工作目录。不过当前工作目录可能与你期望的不一样,所以在指定文件名时最好指定绝对目录。PHP函数 getcwd() 能指出当前工作目录。

跟踪文件名一般是"{trace_file}.xt"。如果 xdebug.auto_trace 开启,那么文件名"{filename}.xt"的"{filename}"部分由设置 xdebug.trace_output_name 决定。参数options是比特值,有三种选项:

XDEBUG_TRACE_APPEND (1)

使跟踪文件以追加模式打开而不是覆盖模式。

XDEBUG_TRACE_COMPUTERIZED (2)

创建一个跟踪文件而其格式由"xdebug.trace_format"描述。

XDEBUG_TRACE_HTML (4)

以html表格创建跟踪文件。

XDEBUG_TRACE_NAKED_FILENAME (8)

一般来说,Xdebug会添加".xt"到你指定的第一个参数的文件名结尾。使用XDEBUG_TRACE_NAKED_FILENAME选项, ".xt" 则不会再添加 (Xdebug 2.3新特性).

不像Xdebug 1,Xdebug 2不会在函数调用时占用内存。,但它会写入磁盘而缓解内存使用的压力。 xdebug.collect_includesxdebug.collect_params 和xdebug.collect_return 等设置会影响跟踪文件记录什么样的信息,而xdebug.trace_format 则影响文件信息的格式。

void xdebug_stop_trace()

停止跟踪函数调用并关闭跟踪文件。