.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "UFTRACE\-REPLAY" "1" "May, 2016" "Uftrace User Manuals" ""
.hy
.SH NAME
.PP
uftrace\-replay \- Print recorded function trace
.SH SYNOPSIS
.PP
uftrace replay [\f[I]options\f[]]
.SH DESCRIPTION
.PP
This command prints trace data recorded using the
\f[C]uftrace\-record\f[](1) command.
The traced functions are printed like a C program in time order.
.SH OPTIONS
.TP
.B \-\-flat
Print flat format rather than C\-like format.
This is usually for debugging and testing purpose.
.RS
.RE
.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 \f[I]FILTERS\f[].
.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 \f[I]FILTERS\f[].
.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 \f[I]TRIGGERS\f[].
.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 \-f \f[I]FIELD\f[], \-\-output\-fields=\f[I]FIELD\f[]
Customize field in the output.
Possible values are: duration, tid, addr, time, delta, elapsed, task and
module.
Multiple fields can be set by using comma.
Special field of `none' can be used (solely) to hide all fields.
Default is `duration,tid'.
See \f[I]FIELDS\f[].
.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 <start>~<stop> (separated by \[lq]~\[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[] or
\f[C]\-f\ elapsed\f[] option respectively.
.RS
.RE
.TP
.B \-\-disable
Start uftrace with tracing disabled.
This is only meaningful when used with a \f[C]trace_on\f[] trigger.
.RS
.RE
.TP
.B \-\-demangle=\f[I]TYPE\f[]
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.
.RS
.RE
.TP
.B \[en]column\-view
Show each task in separate column.
This makes easy to distinguish functions in different tasks.
.RS
.RE
.TP
.B \[en]column\-offset=\f[I]DEPTH\f[]
When \f[C]\-\-column\-view\f[] option is used, this option specifies the
amount of offset between each task.
Default is 8.
.RS
.RE
.TP
.B \[en]task\-newline
Interleave a new line when task is changed.
This makes easy to distinguish functions in different tasks.
.RS
.RE
.TP
.B \[en]no\-comment
Do not show comments of returned functions.
.RS
.RE
.TP
.B \-k, \-\-kernel
Trace kernel functions (and events) as well as user functions (and
events).
This options has no meaning and so is deprecated now.
It will always show kernel functions and events if exists.
If you want to hide kernel functions, please use \f[C]\-N\ .\@kernel\f[]
to filter out all kernel functions (for the regex match).
.RS
.RE
.TP
.B \-\-kernel\-full
Show all kernel functions and events occurred outside of user functions.
This option is the inverse of \f[C]\-\-kernel\-skip\-out\f[].
.RS
.RE
.TP
.B \-\-kernel\-skip\-out
Do not show kernel functions called outside of user functions.
This option is deprecated and set to true by default.
.RS
.RE
.TP
.B \-\-kernel\-only
Show kernel functions only without user functions.
.RS
.RE
.TP
.B \-\-event\-full
Show all (user) events outside of user functions.
.RS
.RE
.TP
.B \-\-no\-event
Do not show any events.
.RS
.RE
.TP
.B \-\-libname
Show libname name along with function name.
.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 FILTERS
.PP
The uftrace tool supports filtering out uninteresting functions.
When uftrace is called it receives two types of function filter; an
opt\-in filter with \f[C]\-F\f[]/\f[C]\-\-filter\f[] and an opt\-out
filter with \f[C]\-N\f[]/\f[C]\-\-notrace\f[].
These filters can be applied either at record time or replay time.
.PP
The first one is an opt\-in filter.
By default, it doesn't show anything.
But when one of the specified functions is met, printing is started.
When the function returns, printing is stopped again.
.PP
For example, consider a simple program which calls \f[C]a()\f[],
\f[C]b()\f[] and \f[C]c()\f[] in turn.
.IP
.nf
\f[C]
$\ cat\ abc.c
void\ c(void)\ {
\ \ \ \ /*\ do\ nothing\ */
}

void\ b(void)\ {
\ \ \ \ c();
}

void\ a(void)\ {
\ \ \ \ b();
}

int\ main(void)\ {
\ \ \ \ a();
\ \ \ \ return\ 0;
}

$\ gcc\ \-pg\ \-o\ abc\ abc.c
\f[]
.fi
.PP
Normally uftrace replay will show all the functions from \f[C]main()\f[]
to \f[C]c()\f[].
.IP
.nf
\f[C]
$\ uftrace\ ./abc
#\ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION
\ 138.494\ us\ [\ 1234]\ |\ __cxa_atexit();
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ main()\ {
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ \ \ a()\ {
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ \ \ \ \ b()\ {
\ \ \ 3.880\ us\ [\ 1234]\ |\ \ \ \ \ \ \ c();
\ \ \ 5.475\ us\ [\ 1234]\ |\ \ \ \ \ }\ /*\ b\ */
\ \ \ 6.448\ us\ [\ 1234]\ |\ \ \ }\ /*\ a\ */
\ \ \ 8.631\ us\ [\ 1234]\ |\ }\ /*\ main\ */
\f[]
.fi
.PP
But when the \f[C]\-F\ b\f[] filter option is used, it will not show
\f[C]main()\f[] or \f[C]a()\f[] but only \f[C]b()\f[] and \f[C]c()\f[].
Note that the filter was set on \f[C]uftrace\ replay\f[], not at record
time.
.IP
.nf
\f[C]
$\ uftrace\ record\ ./abc
$\ uftrace\ replay\ \-F\ b
#\ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ b()\ {
\ \ \ 3.880\ us\ [\ 1234]\ |\ \ \ c();
\ \ \ 5.475\ us\ [\ 1234]\ |\ }\ /*\ b\ */
\f[]
.fi
.PP
The second type of filter is opt\-out.
When used, everything is shown by default, but printing stops once one
of the specified functions is met.
When the given function returns, printing is started again.
.PP
In the above example, you can omit the function \f[C]b()\f[] and all
calls it makes with the \f[C]\-N\f[] option.
.IP
.nf
\f[C]
$\ uftrace\ record\ ./abc
$\ uftrace\ replay\ \-N\ b
#\ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION
\ 138.494\ us\ [\ 1234]\ |\ __cxa_atexit();
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ main()\ {
\ \ \ 6.448\ us\ [\ 1234]\ |\ \ \ a();
\ \ \ 8.631\ us\ [\ 1234]\ |\ }\ /*\ main\ */
\f[]
.fi
.PP
In addition, you can limit the print nesting level with \-D option.
.IP
.nf
\f[C]
$\ uftrace\ record\ ./abc
$\ uftrace\ replay\ \-D\ 3
#\ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION
\ 138.494\ us\ [\ 1234]\ |\ __cxa_atexit();
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ main()\ {
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ \ \ a()\ {
\ \ \ 5.475\ us\ [\ 1234]\ |\ \ \ \ \ b();
\ \ \ 6.448\ us\ [\ 1234]\ |\ \ \ }\ /*\ a\ */
\ \ \ 8.631\ us\ [\ 1234]\ |\ }\ /*\ main\ */
\f[]
.fi
.PP
In the above example, uftrace only prints functions up to a depth of 3,
so leaf function \f[C]c()\f[] was omitted.
Note that the \f[C]\-D\f[] option also works with \f[C]\-F\f[].
.PP
Sometimes it's useful to see long\-running functions only.
This is good because there are usually many tiny functions that are not
interesting.
The \f[C]\-t\f[]/\f[C]\-\-time\-filter\f[] option implements the
time\-based filter that only records functions which run longer than the
given threshold.
In the above example, the user might want to see functions running more
than 5 microseconds like below:
.IP
.nf
\f[C]
$\ uftrace\ record\ ./abc
$\ uftrace\ replay\ \-t\ 5us
#\ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION
\ 138.494\ us\ [\ 1234]\ |\ __cxa_atexit();
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ main()\ {
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ \ \ a()\ {
\ \ \ 5.475\ us\ [\ 1234]\ |\ \ \ \ \ b();
\ \ \ 6.448\ us\ [\ 1234]\ |\ \ \ }\ /*\ a\ */
\ \ \ 8.631\ us\ [\ 1234]\ |\ }\ /*\ main\ */
\f[]
.fi
.PP
You can also see replay output with different time threshold for the
same recorded data.
.IP
.nf
\f[C]
$\ uftrace\ replay\ \-t\ 6us
#\ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION
\ 138.494\ us\ [\ 1234]\ |\ __cxa_atexit();
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ main()\ {
\ \ \ 6.448\ us\ [\ 1234]\ |\ \ \ a();
\ \ \ 8.631\ us\ [\ 1234]\ |\ }\ /*\ main\ */
\f[]
.fi
.PP
In addition, The \f[C]\-r\f[] option can show functions executed within
the given time range.
When using this option, you can see TIMESTAMP or ELAPSED fields as well
as DURATION and TID.
.IP
.nf
\f[C]
$\ uftrace\ replay\ \-r\ 502716.387320101~502716.387322389
#\ \ \ \ \ TIMESTAMP\ \ \ \ \ \ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION
502716.387320101\ \ \ 0.289\ us\ [\ 6126]\ |\ \ \ fgets();
502716.387320584\ \ \ \ \ \ \ \ \ \ \ \ [\ 6126]\ |\ \ \ get_values_from()\ {
502716.387320709\ \ \ 0.245\ us\ [\ 6126]\ |\ \ \ \ \ strdup();
502716.387321172\ \ \ 0.144\ us\ [\ 6126]\ |\ \ \ \ \ strsep();
502716.387321542\ \ \ 0.223\ us\ [\ 6126]\ |\ \ \ \ \ atoi();
502716.387321983\ \ \ 0.239\ us\ [\ 6126]\ |\ \ \ \ \ atoi();
502716.387322389\ \ \ 1.805\ us\ [\ 6126]\ |\ \ \ }\ /*\ get_values_from\ */

$\ uftrace\ replay\ \-r\ 40us~\ |\ head\ \-10
#\ \ ELAPSED\ \ \ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION
\ \ 40.141\ us\ \ \ \ \ \ \ \ \ \ \ \ [\ 6126]\ |\ \ \ get_values_from()\ {
\ \ 40.269\ us\ \ \ 0.249\ us\ [\ 6126]\ |\ \ \ \ \ strdup();
\ \ 40.756\ us\ \ \ 0.149\ us\ [\ 6126]\ |\ \ \ \ \ strsep();
\ \ 41.119\ us\ \ \ 0.235\ us\ [\ 6126]\ |\ \ \ \ \ atoi();
\ \ 41.578\ us\ \ \ 0.211\ us\ [\ 6126]\ |\ \ \ \ \ atoi();
\ \ 41.957\ us\ \ \ 1.816\ us\ [\ 6126]\ |\ \ \ }\ /*\ get_values_from\ */
\ \ 42.124\ us\ \ \ 0.220\ us\ [\ 6126]\ |\ \ \ fgets();
\ \ 42.529\ us\ \ \ \ \ \ \ \ \ \ \ \ [\ 6126]\ |\ \ \ get_values_from()\ {
\ \ 42.645\ us\ \ \ 0.236\ us\ [\ 6126]\ |\ \ \ \ \ strdup();
\f[]
.fi
.PP
You can also set triggers on filtered functions.
See \f[I]TRIGGERS\f[] section below for details.
.SH TRIGGERS
.PP
The uftrace tool supports triggering actions on selected function calls
with or without filters.
Currently supported triggers are \f[C]depth\f[], \f[C]backtrace\f[],
\f[C]trace_on\f[] and \f[C]trace_off\f[].
The BNF for trigger specifications is like below:
.IP
.nf
\f[C]
<trigger>\ \ \ \ :=\ \ <symbol>\ "\@"\ <actions>
<actions>\ \ \ \ :=\ \ <action>\ \ |\ <action>\ ","\ <actions>
<action>\ \ \ \ \ :=\ \ "depth="<num>\ |\ "backtrace"\ |\ "trace_on"\ |\ "trace_off"\ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "color="<color>\ |\ "time="<time_spec>\ |\ "filter"\ |\ "notrace"
<time_spec>\ \ :=\ \ <num>\ [\ <time_unit>\ ]
<time_unit>\ \ :=\ \ "ns"\ |\ "nsec"\ |\ "us"\ |\ "usec"\ |\ "ms"\ |\ "msec"\ |\ "s"\ |\ "sec"\ |\ "m"\ |\ "min"
\f[]
.fi
.PP
The \f[C]depth\f[] trigger is to change filter depth during execution of
the function.
It can be used to apply different filter depths for different functions.
And the \f[C]backtrace\f[] trigger is used to print a stack backtrace at
replay time.
.PP
The color trigger is to change the color of the function in replay
output.
The supported colors are \f[C]red\f[], \f[C]green\f[], \f[C]blue\f[],
\f[C]yellow\f[], \f[C]magenta\f[], \f[C]cyan\f[], \f[C]bold\f[], and
\f[C]gray\f[].
.PP
The following example shows how triggers work.
We set a filter on function \f[C]b()\f[] with the \f[C]backtrace\f[]
action and change the maximum filter depth under \f[C]b()\f[] to 2.
.IP
.nf
\f[C]
$\ uftrace\ record\ ./abc
$\ uftrace\ replay\ \-T\ \[aq]b\@filter,backtrace,depth=2\[aq]
#\ DURATION\ \ \ \ TID\ \ \ \ \ FUNCTION
\ \ backtrace\ [\ 1234]\ |\ /*\ [\ 0]\ main\ */
\ \ backtrace\ [\ 1234]\ |\ /*\ [\ 1]\ a\ */
\ \ \ \ \ \ \ \ \ \ \ \ [\ 1234]\ |\ b\ {
\ \ \ 3.880\ us\ [\ 1234]\ |\ \ \ c();
\ \ \ 5.475\ us\ [\ 1234]\ |\ }\ /*\ b\ */
\f[]
.fi
.PP
The \f[C]traceon\f[] and \f[C]traceoff\f[] actions (the \f[C]_\f[] can
be omitted from \f[C]trace_on\f[] and \f[C]trace_off\f[]) control
whether uftrace shows functions or not.
The trigger runs at replay time, not run time, so it can handle kernel
functions as well.
Contrast this with triggers used under \f[C]uftrace\ record\f[].
.PP
The `time' trigger is to change time filter setting during execution of
the function.
It can be used to apply different time filter for different functions.
.PP
The `filter' and `notrace' triggers have same effect as \-F/\[en]filter
and \-N/\[en]notrace options respectively.
.SH FIELDS
.PP
The uftrace allows for user to customize the replay output with a couple
of fields.
Here the field means info on the left side of the pipe (|) character.
By default it uses duration and tid fields, but you can use other fields
in any order like:
.IP
.nf
\f[C]
$\ uftrace\ replay\ \-f\ time,delta,duration,addr
#\ \ \ \ \ TIMESTAMP\ \ \ \ \ \ TIMEDELTA\ \ DURATION\ \ \ \ \ ADDRESS\ \ \ \ \ FUNCTION
\ \ \ \ 74469.340757350\ \ \ \ \ \ \ \ \ \ \ \ \ \ 1.583\ us\ \ \ \ \ \ \ 4004d0\ |\ __monstartup();
\ \ \ \ 74469.340762221\ \ \ 4.871\ us\ \ \ 0.766\ us\ \ \ \ \ \ \ 4004f0\ |\ __cxa_atexit();
\ \ \ \ 74469.340764847\ \ \ 2.626\ us\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4006b1\ |\ main()\ {
\ \ \ \ 74469.340765061\ \ \ 0.214\ us\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 400656\ |\ \ \ a()\ {
\ \ \ \ 74469.340765195\ \ \ 0.134\ us\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 400669\ |\ \ \ \ \ b()\ {
\ \ \ \ 74469.340765344\ \ \ 0.149\ us\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 40067c\ |\ \ \ \ \ \ \ c()\ {
\ \ \ \ 74469.340765524\ \ \ 0.180\ us\ \ \ 0.742\ us\ \ \ \ \ \ \ 4004b0\ |\ \ \ \ \ \ \ \ \ getpid();
\ \ \ \ 74469.340766935\ \ \ 1.411\ us\ \ \ 1.591\ us\ \ \ \ \ \ \ 40067c\ |\ \ \ \ \ \ \ }\ /*\ c\ */
\ \ \ \ 74469.340767195\ \ \ 0.260\ us\ \ \ 2.000\ us\ \ \ \ \ \ \ 400669\ |\ \ \ \ \ }\ /*\ b\ */
\ \ \ \ 74469.340767372\ \ \ 0.177\ us\ \ \ 2.311\ us\ \ \ \ \ \ \ 400656\ |\ \ \ }\ /*\ a\ */
\ \ \ \ 74469.340767541\ \ \ 0.169\ us\ \ \ 2.694\ us\ \ \ \ \ \ \ 4006b1\ |\ }\ /*\ main\ */
\f[]
.fi
.PP
Each field has following meaning:
.IP \[bu] 2
tid: task id (obtained by gettid(2))
.IP \[bu] 2
duration: function execution time
.IP \[bu] 2
time: timestamp at the execution
.IP \[bu] 2
delta: difference between two timestamp in a task
.IP \[bu] 2
elapsed: elapsed time from the first timestamp
.IP \[bu] 2
addr: address of the function
.IP \[bu] 2
task: task name (comm)
.IP \[bu] 2
module: library or executable name of the function
.PP
The default value is `duration,tid'.
If given field name starts with \[lq]+\[rq], then it'll be appended to
the default fields.
So \[lq]\-f +time\[rq] is as same as \[lq]\-f duration,tid,time\[rq].
And it also accepts a special field name of `none' which disables the
field display and shows function output only.
.SH SEE ALSO
.PP
\f[C]uftrace\f[](1), \f[C]uftrace\-record\f[](1),
\f[C]uftrace\-report\f[](1), \f[C]uftrace\-info\f[](1)
.SH AUTHORS
Namhyung Kim <namhyung@gmail.com>.