Provided by: uftrace_0.16-1_amd64 
NAME
uftrace-script - Run a script for recorded function trace
SYNOPSIS
uftrace script (-S|–script) [options] uftrace script (-S|–script)
[options] –record COMMAND
DESCRIPTION
This command runs a script for trace data recorded using the uftrace-record(1) command.
SCRIPT OPTIONS
-S SCRIPT_PATH, --script=SCRIPT_PATH
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 SCRIPT
EXECUTION.
--record COMMAND [command-options]
Record a new trace before running a given script.
--no-args
Do not show function arguments and return value.
COMMON OPTIONS
-F FUNC, --filter=FUNC
Set filter to trace selected functions and their children functions. This option
can be used more than once. See uftrace-replay(1) for an explanation of filters.
-N FUNC, --notrace=FUNC
Set filter not to trace selected functions and their children functions. This
option can be used more than once. See uftrace-replay(1) for an explanation of
filters.
-C FUNC, --caller-filter=FUNC
Set filter to trace callers of selected functions only. This option can be used
more than once. See uftrace-replay(1) for an explanation of filters.
-T TRG, --trigger=TRG
Set trigger on selected functions. This option can be used more than once. See
`uftrace-replay' for details.
-D DEPTH, --depth DEPTH
Set trace limit in nesting level.
-t TIME, --time-filter=TIME
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.
-Z SIZE, --size-filter=SIZE
Do not show functions smaller than SIZE bytes.
-L LOCATION, --loc-filter=LOCATION
Set filter to trace selected source locations. This option can be used more than
once.
--no-libcall
Do not run script for library calls.
--match=TYPE
Use pattern match using TYPE. Possible types are regex and glob. Default is
regex.
--with-syms=DIR
Read symbol data from the .sym files in DIR directory instead of the binary. This
can be useful to deal with stripped binaries. The file name of the main binary
should be the same when saved and used.
COMMON ANALYSIS OPTIONS
-H FUNC, --hide=FUNC
Set filter not to trace selected functions. It doesn’t affect their subtrees, but
hides only the given functions. This option can be used more than once. See
uftrace-replay(1) for an explanation of filters.
--kernel-full
Run script all kernel functions and events occurred outside of user functions.
--kernel-only
Run script kernel functions only without user functions.
--tid=TID[,TID,...]
Run script only for functions called by the given tasks. To see the list of tasks
in the data file, you can use uftrace report --task or uftrace info. This option
can also be used more than once.
--demangle=TYPE
Use demangled C++ symbol names for filters, triggers, arguments and/or return
values. Possible values are “full”, “simple” and “no”. Default is “simple” which
ignores function arguments and template parameters.
-r RANGE, --time-range=RANGE
Run script only for functions executed within the time RANGE. The RANGE can be
<start>~<stop> (separated by “~”) 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
time or -f elapsed option respectively in uftrace replay(1).
SCRIPT EXECUTION
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.
The user can write five 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.
`uftrace_event' is called when it sees an event.
$ 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_event(ctx):
name = ctx["name"]
print("event : " + name)
def uftrace_end():
print("program is finished")
The `ctx' variable is a dictionary type that contains the below information.
/* 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
};
The above script can be executed while reading the recorded data. The usage is as
follows:
$ 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
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.
$ 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 */
The script above can be modified to do more output customization.
A script can have an optional “UFTRACE_FUNCS” list which can have name (or pattern
depending on the –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.
$ echo 'UFTRACE_FUNCS = [ "^.$" ]' >> 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 */
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 “uftrace-option:” will provide (a
part of) such options when recording.
$ 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
Also a script can handle event records and optional event data in “args”. The argument is
a string containing KEY=VALUE pairs. Currently it only works with uftrace script and not
for record.
$ cat event.py
def uftrace_entry(ctx):
pass
def uftrace_exit(ctx):
pass
def uftrace_event(ctx):
if "args" in ctx:
print(ctx["name"] + " ::: " + ctx["args"])
else:
print(ctx["name"])
$ uftrace record -T a@read=proc/statm abc
$ uftrace script -S event.py
read:proc/statm ::: vmsize=31060KB vmrss=15412KB shared=11064KB
diff:proc/statm ::: vmsize=+0KB vmrss=+0KB shared=+0KB
SEE ALSO
uftrace(1), uftrace-record(1), uftrace-replay(1), uftrace-live(1)
AUTHORS
Honggyu Kim <honggyu.kp@gmail.com>, Namhyung Kim <namhyung@gmail.com>.