.\" Automatically generated by Pandoc 2.2.1 .\" .TH "UFTRACE\-SCRIPT" "1" "July, 2017" "Uftrace User Manuals" "" .hy .SH NAME .PP uftrace\-script \- Run a script for recorded function trace .SH SYNOPSIS .PP uftrace script [\f[I]options\f[]] .SH DESCRIPTION .PP This command runs a script for trace data recorded using the \f[C]uftrace\-record\f[](1) command. .SH OPTIONS .TP .B \-F \f[I]FUNC\f[], \-\-filter=\f[I]FUNC\f[] Set filter to trace selected functions only. This option can be used more than once. See `uftrace\-replay' for details. .RS .RE .TP .B \-N \f[I]FUNC\f[], \-\-notrace=\f[I]FUNC\f[] Set filter not to trace selected functions (or the functions called underneath them). This option can be used more than once. See `uftrace\-replay' for details. .RS .RE .TP .B \-T \f[I]TRG\f[], \-\-trigger=\f[I]TRG\f[] Set trigger on selected functions. This option can be used more than once. See `uftrace\-replay' for details. .RS .RE .TP .B \-t \f[I]TIME\f[], \-\-time\-filter=\f[I]TIME\f[] Do not show functions which run under the time threshold. If some functions explicitly have the `trace' trigger applied, those are always traced regardless of execution time. .RS .RE .TP .B \-\-tid=\f[I]TID\f[][,\f[I]TID\f[],\&...] Only print functions called by the given threads. To see the list of threads in the data file, you can use \f[C]uftrace\ report\ \-\-threads\f[] or \f[C]uftrace\ info\f[]. This option can also be used more than once. .RS .RE .TP .B \-D \f[I]DEPTH\f[], \-\-depth \f[I]DEPTH\f[] Set trace limit in nesting level. .RS .RE .TP .B \-r \f[I]RANGE\f[], \-\-time\-range=\f[I]RANGE\f[] Only show functions executed within the time RANGE. The RANGE can be ~ (separated by \[lq]~\[rq]) and one of and can be omitted. The and are timestamp or elapsed time if they have postfix, for example `100us'. The timestamp or elapsed time can be shown with \f[C]\-f\ time\f[] or \f[C]\-f\ elapsed\f[] option respectively. .RS .RE .TP .B \-S \f[I]SCRIPT_PATH\f[], \-\-script=\f[I]SCRIPT_PATH\f[] Add a script to do additional work at the entry and exit of function. The type of script is detected by the postfix such as `.py' for python. .RS .RE .TP .B \-\-record COMMAND [\f[I]command\-options\f[]] Record a new trace before running a given script. .RS .RE .TP .B \[en]match=\f[I]TYPE\f[] Use pattern match using TYPE. Possible types are \f[C]regex\f[] and \f[C]glob\f[]. Default is \f[C]regex\f[]. .RS .RE .SH EXAMPLES .PP The uftrace tool supports script execution for each function entry and exit. The supported script is only Python 2.7 as of now. .PP The user can write four functions. `uftrace_entry' and `uftrace_exit' are executed whenever each function is executed at the entry and exit. However `uftrace_begin' and `uftrace_end' are only executed once when the target program begins and ends. .IP .nf \f[C] $\ cat\ scripts/simple.py def\ uftrace_begin(ctx): \ \ \ \ print("program\ begins...") def\ uftrace_entry(ctx): \ \ \ \ func\ =\ ctx["name"] \ \ \ \ print("entry\ :\ "\ +\ func\ +\ "()") def\ uftrace_exit(ctx): \ \ \ \ func\ =\ ctx["name"] \ \ \ \ print("exit\ \ :\ "\ +\ func\ +\ "()") def\ uftrace_end(): \ \ \ \ print("program\ is\ finished") \f[] .fi .PP The `ctx' variable is a dictionary type that contains the below information. .IP .nf \f[C] /*\ context\ information\ passed\ to\ script\ */ script_context\ =\ { \ \ \ \ int\ \ \ \ \ \ \ tid; \ \ \ \ int\ \ \ \ \ \ \ depth; \ \ \ \ long\ \ \ \ \ \ timestamp; \ \ \ \ long\ \ \ \ \ \ duration;\ \ \ \ #\ exit\ only \ \ \ \ long\ \ \ \ \ \ address; \ \ \ \ string\ \ \ \ name; \ \ \ \ list\ \ \ \ \ \ args;\ \ \ \ \ \ \ \ #\ entry\ only\ (if\ available) \ \ \ \ value\ \ \ \ \ retval;\ \ \ \ \ \ #\ exit\ \ only\ (if\ available) }; \f[] .fi .PP The above script can be executed while reading the recorded data. The usage is as follows: .IP .nf \f[C] $\ uftrace\ record\ \-F\ main\ tests/t\-abc $\ uftrace\ script\ \-S\ scripts/simple.py program\ begins... entry\ :\ main() entry\ :\ a() entry\ :\ b() entry\ :\ c() entry\ :\ getpid() exit\ \ :\ getpid() exit\ \ :\ c() exit\ \ :\ b() exit\ \ :\ a() exit\ \ :\ main() program\ is\ finished \f[] .fi .PP The below is another example that shows the different output compared to previous one for the same recorded data. The output looks similar to `uftrace replay' this time. .IP .nf \f[C] $\ uftrace\ script\ \-S\ scripts/replay.py #\ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION \ \ \ \ \ \ \ \ \ \ \ \ [25794]\ |\ main()\ { \ \ \ \ \ \ \ \ \ \ \ \ [25794]\ |\ \ \ a()\ { \ \ \ \ \ \ \ \ \ \ \ \ [25794]\ |\ \ \ \ \ b()\ { \ \ \ \ \ \ \ \ \ \ \ \ [25794]\ |\ \ \ \ \ \ \ c()\ { \ \ \ \ \ \ \ \ \ \ \ \ [25794]\ |\ \ \ \ \ \ \ \ \ getpid()\ { \ \ 11.037\ us\ [25794]\ |\ \ \ \ \ \ \ \ \ }\ /*\ getpid\ */ \ \ 44.752\ us\ [25794]\ |\ \ \ \ \ \ \ }\ /*\ c\ */ \ \ 70.924\ us\ [25794]\ |\ \ \ \ \ }\ /*\ b\ */ \ \ 98.191\ us\ [25794]\ |\ \ \ }\ /*\ a\ */ \ 124.329\ us\ [25794]\ |\ }\ /*\ main\ */ \f[] .fi .PP The python script above can be modified to do more output customization. .PP The python script can have an optional \[lq]UFTRACE_FUNCS\[rq] list which can have name (or pattern depending on the \[en]match option) of functions to run the script. If it exists, only matched functions will run the script. For example, if you add following lines to the script, it will run only for functions with a single letter name. .IP .nf \f[C] $\ echo\ \[aq]UFTRACE_FUNCS\ =\ [\ "^.$"\ ]\[aq]\ >>\ replay.py $\ uftrace\ script\ \-S\ replay.py #\ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION \ \ \ \ \ \ \ \ \ \ \ \ [25794]\ |\ \ \ a()\ { \ \ \ \ \ \ \ \ \ \ \ \ [25794]\ |\ \ \ \ \ b()\ { \ \ \ \ \ \ \ \ \ \ \ \ [25794]\ |\ \ \ \ \ \ \ c()\ { \ \ 44.752\ us\ [25794]\ |\ \ \ \ \ \ \ }\ /*\ c\ */ \ \ 70.924\ us\ [25794]\ |\ \ \ \ \ }\ /*\ b\ */ \ \ 98.191\ us\ [25794]\ |\ \ \ }\ /*\ a\ */ \f[] .fi .PP Also script can have options for record if it requires some form of data (i.e.\ function argument or return value). A comment line started with \[lq]uftrace\-option:\[rq] will provide (a part of) such options when recording. .IP .nf \f[C] $\ cat\ arg.py # #\ uftrace\-option:\ \-A\ a\@arg1\ \-R\ b\@retval # def\ uftrace_entry(ctx): \ \ \ \ if\ "args"\ in\ ctx: \ \ \ \ \ \ \ \ print(ctx["name"]\ +\ "\ has\ args") def\ uftrace_exit(ctx): \ \ \ \ if\ "retval"\ in\ ctx: \ \ \ \ \ \ \ \ print(ctx["name"]\ +\ "\ has\ retval") $\ uftrace\ record\ \-S\ arg.py\ abc a\ has\ args b\ has\ retval $\ uftrace\ script\ \-S\ arg.py a\ has\ args b\ has\ retval \f[] .fi .SH SEE ALSO .PP \f[C]uftrace\f[](1), \f[C]uftrace\-record\f[](1), \f[C]uftrace\-replay\f[](1), \f[C]uftrace\-live\f[](1) .SH AUTHORS Honggyu Kim .