.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "UFTRACE-SCRIPT" "1" "Sep, 2018" "Uftrace User Manuals" ""
.hy
.SH NAME
.PP
uftrace-script - Run a script for recorded function trace
.SH SYNOPSIS
uftrace script (-S|\[en]script)
[\f[I]options\f[R]] uftrace script (-S|\[en]script)
.PP
[\f[I]options\f[R]] \[en]record COMMAND
.SH DESCRIPTION
.PP
This command runs a script for trace data recorded using the
\f[C]uftrace-record\f[R](1) command.
.SH SCRIPT OPTIONS
.TP
-S \f[I]SCRIPT_PATH\f[R], --script=\f[I]SCRIPT_PATH\f[R]
Run a given script to do additional work at the entry and exit of
function while processing recorded trace data.
The type of script is detected by the file extension.
For example `.py' for python and `.lua' for lua 5.1.
See \f[I]SCRIPT EXECUTION\f[R].
.TP
--record COMMAND [\f[I]command-options\f[R]]
Record a new trace before running a given script.
.SH COMMON OPTIONS
.TP
-F \f[I]FUNC\f[R], --filter=\f[I]FUNC\f[R]
Set filter to trace selected functions and their children functions.
This option can be used more than once.
See \f[C]uftrace-replay\f[R](1) for an explanation of filters.
.TP
-N \f[I]FUNC\f[R], --notrace=\f[I]FUNC\f[R]
Set filter not to trace selected functions and their children functions.
This option can be used more than once.
See \f[C]uftrace-replay\f[R](1) for an explanation of filters.
.TP
-C \f[I]FUNC\f[R], --caller-filter=\f[I]FUNC\f[R]
Set filter to trace callers of selected functions only.
This option can be used more than once.
See \f[C]uftrace-replay\f[R](1) for an explanation of filters.
.TP
-T \f[I]TRG\f[R], --trigger=\f[I]TRG\f[R]
Set trigger on selected functions.
This option can be used more than once.
See `uftrace-replay' for details.
.TP
-D \f[I]DEPTH\f[R], --depth \f[I]DEPTH\f[R]
Set trace limit in nesting level.
.TP
-t \f[I]TIME\f[R], --time-filter=\f[I]TIME\f[R]
Do not run script for functions which run under the time threshold.
If some functions explicitly have the `trace' trigger applied, those are
always traced regardless of execution time.
.TP
--no-libcall
Do not run script for library calls.
.TP
--match=\f[I]TYPE\f[R]
Use pattern match using TYPE.
Possible types are \f[C]regex\f[R] and \f[C]glob\f[R].
Default is \f[C]regex\f[R].
.SH COMMON ANALYSIS OPTIONS
.TP
-H \f[I]FUNC\f[R], --hide=\f[I]FUNC\f[R]
Set filter not to trace selected functions.
It doesn\[cq]t affect their subtrees, but hides only the given
functions.
This option can be used more than once.
See \f[C]uftrace-replay\f[R](1) for an explanation of filters.
.TP
--kernel-full
Run script all kernel functions and events occurred outside of user
functions.
.TP
--kernel-only
Run script kernel functions only without user functions.
.TP
--tid=\f[I]TID\f[R][,\f[I]TID\f[R],\&...]
Run script only for functions called by the given tasks.
To see the list of tasks in the data file, you can use
\f[C]uftrace report --task\f[R] or \f[C]uftrace info\f[R].
This option can also be used more than once.
.TP
--demangle=\f[I]TYPE\f[R]
Use demangled C++ symbol names for filters, triggers, arguments and/or
return values.
Possible values are \[lq]full\[rq], \[lq]simple\[rq] and \[lq]no\[rq].
Default is \[lq]simple\[rq] which ignores function arguments and
template parameters.
.TP
-r \f[I]RANGE\f[R], --time-range=\f[I]RANGE\f[R]
Run script only for functions executed within the time RANGE.
The RANGE can be <start>\[ti]<stop> (separated by \[lq]\[ti]\[rq]) and
one of <start> and <stop> can be omitted.
The <start> and <stop> are timestamp or elapsed time if they have
<time_unit> postfix, for example `100us'.
The timestamp or elapsed time can be shown with \f[C]-f time\f[R] or
\f[C]-f elapsed\f[R] option respectively in \f[C]uftrace replay\f[R](1).
.SH SCRIPT EXECUTION
.PP
The uftrace tool supports script execution for each function entry and
exit.
The supported script types are Python 2.7, Python 3 and Lua 5.1 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(\[dq]program begins...\[dq])

def uftrace_entry(ctx):
    func = ctx[\[dq]name\[dq]]
    print(\[dq]entry : \[dq] + func + \[dq]()\[dq])

def uftrace_exit(ctx):
    func = ctx[\[dq]name\[dq]]
    print(\[dq]exit  : \[dq] + func + \[dq]()\[dq])

def uftrace_end():
    print(\[dq]program is finished\[dq])
\f[R]
.fi
.PP
The `ctx' variable is a dictionary type that contains the below
information.
.IP
.nf
\f[C]
/* context information passed to uftrace_entry(ctx) and uftrace_exit(ctx) */
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)
};

/* context information passed to uftrace_begin(ctx) */
script_context = {
    bool      record;      # True if it runs at record time, otherwise False
    string    version;     # uftrace version info
    list      cmds;        # execution commands
};
\f[R]
.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[R]
.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 \f[C]uftrace replay\f[R] 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[R]
.fi
.PP
The script above can be modified to do more output customization.
.PP
A 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 = [ \[dq]\[ha].$\[dq] ]\[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[R]
.fi
.PP
Also a 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\[at]arg1 -R b\[at]retval
#
def uftrace_entry(ctx):
    if \[dq]args\[dq] in ctx:
        print(ctx[\[dq]name\[dq]] + \[dq] has args\[dq])
def uftrace_exit(ctx):
    if \[dq]retval\[dq] in ctx:
        print(ctx[\[dq]name\[dq]] + \[dq] has retval\[dq])

$ uftrace record -S arg.py abc
a has args
b has retval
$ uftrace script -S arg.py
a has args
b has retval
\f[R]
.fi
.SH SEE ALSO
.PP
\f[C]uftrace\f[R](1), \f[C]uftrace-record\f[R](1),
\f[C]uftrace-replay\f[R](1), \f[C]uftrace-live\f[R](1)
.SH AUTHORS
Honggyu Kim <honggyu.kp@gmail.com>, Namhyung Kim <namhyung@gmail.com>.