.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "UFTRACE-REPORT" "1" "Sep, 2018" "Uftrace User Manuals" ""
.hy
.SH NAME
.PP
uftrace-report - Print statistics and summary for trace data
.SH SYNOPSIS
.PP
uftrace report [\f[I]options\f[R]]
.SH DESCRIPTION
.PP
This command collects trace data from a given data file and prints
statistics and summary information.
It shows function statistics by default, but can show task statistics
with the \f[C]--task\f[R] option and show differences between traces
with the \f[C]--diff\f[R] option.
.SH REPORT OPTIONS
.TP
-f \f[I]FIELD\f[R], --output-fields=\f[I]FIELD\f[R]
Customize field in the output.
Possible values are: \f[C]total\f[R], \f[C]total-avg\f[R],
\f[C]total-min\f[R], \f[C]total-max\f[R], \f[C]self\f[R],
\f[C]self-avg\f[R], \f[C]self-min\f[R], \f[C]self-max\f[R] and
\f[C]call\f[R].
Multiple fields can be set by using comma.
Special field of `none' can be used (solely) to hide all fields.
Default is `total,self,call'.
See \f[I]FIELDS\f[R].
.TP
-s \f[I]KEYS\f[R][,\f[I]KEYS\f[R],\&...], --sort=\f[I]KEYS\f[R][,\f[I]KEYS\f[R],\&...]
Sort functions by given KEYS.
Multiple KEYS can be given, separated by comma (,).
Possible keys are \f[C]total\f[R] (time), \f[C]total-avg\f[R],
\f[C]total-min\f[R], \f[C]total-max\f[R], \f[C]self\f[R] (time),
\f[C]self-avg\f[R], \f[C]self-min\f[R], \f[C]self-max\f[R],
\f[C]call\f[R] and \f[C]func\f[R].
But if either \f[C]--avg-total\f[R] or \f[C]--avg-self\f[R] is used, the
possible keys can be \f[C]avg\f[R], \f[C]min\f[R] and \f[C]max\f[R] that
apply to total or self time respectively.
.TP
--avg-total
Show average, min, max of each function\[cq]s total time.
.TP
--avg-self
Show average, min, max of each function\[cq]s self time.
.TP
--task
Report task summary information rather than function statistics.
Customize field in the output with -f option.
Possible values are: \f[C]total\f[R], \f[C]self\f[R], \f[C]func\f[R] and
\f[C]tid\f[R].
Multiple fields can be set by using comma.
Special field of `none' can be used (solely) to hide all fields.
Default is `total,self,func,tid'.
See \f[I]TASK FIELDS\f[R].
.TP
--diff=\f[I]DATA\f[R]
Report differences between the input trace data and the given DATA.
.TP
--diff-policy=\f[I]POLICY\f[R]
Apply custom diff policy.
Available values are: \[lq]abs\[rq], \[lq]no-abs\[rq],
\[lq]percent\[rq], \[lq]no-percent\[rq], \[lq]compact\[rq] and
\[lq]full\[rq].
The \[lq]abs\[rq] is to sort diff result using absolute value so
positive and negative entries can be shown together while
\[lq]no-abs\[rq] will show positive entries first and then negative
ones.
The \[lq]percent\[rq] is to show diff in percentage while
\[lq]no-percent\[rq] is to show the values.
The \[lq]full\[rq] is to show all three columns of baseline, new data
and difference while \[lq]compact\[rq] only shows the difference.
The default is \[lq]abs\[rq], \[lq]compact\[rq] and
\[lq]no-percent\[rq].
.TP
--sort-column=\f[I]IDX\f[R]
When \f[C]--diff\f[R] is used with \[lq]full\[rq] policy, 3 columns will
be shown for each total time, self time and call count.
This option selects the index of the column to be used as a sort key.
Index 0 is for original data given by the \f[C]--data\f[R] option, index
1 is for data given by the \f[C]--diff\f[R] option, and index 2 is for
(percentage) differences between the two data.
.TP
--srcline
Show source location of each function if available.
.TP
--format=\f[I]TYPE\f[R]
Show format style output.
Currently, normal and html styles are supported.
.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 \f[C]uftrace-replay\f[R](1) for an explanation of triggers.
.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 account functions which run under the time threshold.
If some functions explicitly have the `trace' trigger applied, those are
always accounted regardless of execution time.
.TP
--no-libcall
Do not show library calls.
.TP
--no-event
Do not show any events.
Implies \f[C]--no-sched\f[R].
.TP
--no-sched
Do not show schedule events.
.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
Show all kernel functions, including those called outside of user
functions.
.TP
--kernel-only
Show kernel functions only without user functions.
.TP
--event-full
Show all (user) events outside of user functions.
.TP
--tid=\f[I]TID\f[R][,\f[I]TID\f[R],\&...]
Only print 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]
Only show 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 EXAMPLE
.PP
This command shows information like the following:
.IP
.nf
\f[C]
$ uftrace record abc
$ uftrace report
  Total time   Self time       Calls  Function
  ==========  ==========  ==========  ====================
  150.829 us  150.829 us           1  __cxa_atexit
   27.289 us    1.243 us           1  main
   26.046 us    0.939 us           1  a
   25.107 us    0.934 us           1  b
   24.173 us    1.715 us           1  c
   22.458 us   22.458 us           1  getpid

$ uftrace report -s call,self
  Total time   Self time       Calls  Function
  ==========  ==========  ==========  ====================
  150.829 us  150.829 us           1  __cxa_atexit
   22.458 us   22.458 us           1  getpid
   24.173 us    1.715 us           1  c
   27.289 us    1.243 us           1  main
   26.046 us    0.939 us           1  a
   25.107 us    0.934 us           1  b

$ uftrace report --avg-self
    Avg self    Min self    Max self  Function
  ==========  ==========  ==========  ====================
  150.829 us  150.829 us  150.829 us  __cxa_atexit
   22.458 us   22.458 us   22.458 us  getpid
    1.715 us    1.715 us    1.715 us  c
    1.243 us    1.243 us    1.243 us  main
    0.939 us    0.939 us    0.939 us  a
    0.934 us    0.934 us    0.934 us  b

$ uftrace report --task
  Total time   Self time   Num funcs     TID  Task name
  ==========  ==========  ==========  ======  ================
   22.178 us   22.178 us           7   29955  t-abc

$ uftrace record --srcline abc
$ uftrace report --srcline
  Total time   Self time       Calls  Function [Source]
  ==========  ==========  ==========  ====================
   17.508 us    2.199 us           1  main [./tests/s-abc.c:26]
   15.309 us    2.384 us           1  a [./tests/s-abc.c:11]
   12.925 us    2.633 us           1  b [./tests/s-abc.c:16]
   10.292 us    5.159 us           1  c [./tests/s-abc.c:21]
    5.133 us    5.133 us           1  getpid
    3.437 us    3.437 us           1  __monstartup
    1.959 us    1.959 us           1  __cxa_atexit
\f[R]
.fi
.PP
To see a difference between two data:
.IP
.nf
\f[C]
$ uftrace record abc

$ uftrace report --diff uftrace.data.old
#
# uftrace diff
#  [0] base: uftrace.data       (from uftrace record abc )
#  [1] diff: uftrace.data.old   (from uftrace record abc )
#
  Total time   Self time       Calls  Function
  ==========  ==========  ==========  ====================
   -0.301 us   -0.038 us          +0  main
   -0.263 us   -0.070 us          +0  a
   -0.193 us   -0.042 us          +0  b
   -0.151 us   -0.090 us          +0  c
   -0.131 us   -0.131 us          +0  __cxa_atexit
   -0.061 us   -0.061 us          +0  getpid
\f[R]
.fi
.PP
The above example shows difference sorted by absolute value of total
time.
The following changes it to use (non-absolute) value of self time.
.IP
.nf
\f[C]
$ uftrace report --diff uftrace.data.old -s self --diff-policy no-abs
#
# uftrace diff
#  [0] base: uftrace.data       (from uftrace record abc )
#  [1] diff: uftrace.data.old   (from uftrace record abc )
#
  Total time   Self time       Calls  Function
  ==========  ==========  ==========  ====================
   -0.301 us   -0.038 us          +0  main
   -0.193 us   -0.042 us          +0  b
   -0.061 us   -0.061 us          +0  getpid
   -0.263 us   -0.070 us          +0  a
   -0.151 us   -0.090 us          +0  c
   -0.131 us   -0.131 us          +0  __cxa_atexit
\f[R]
.fi
.PP
By using \[lq]full\[rq] policy, user can see raw data as well like
below.
Also it\[cq]s possible to sort by different column (for raw data).
The example below will sort output by total time of the base data.
.IP
.nf
\f[C]
$ uftrace report --diff uftrace.data.old --sort-column 0 --diff-policy full,percent
#
# uftrace diff
#  [0] base: uftrace.data       (from uftrace record abc )
#  [1] diff: uftrace.data.old   (from uftrace record abc )
#
                 Total time (diff)                   Self time (diff)                  Nr. called (diff)   Function
  ================================   ================================   ================================   ====================
    2.812 us    2.511 us   -10.70%     0.403 us    0.365 us    -9.43%            1          1         +0   main
    2.409 us    2.146 us   -10.92%     0.342 us    0.272 us   -20.47%            1          1         +0   a
    2.067 us    1.874 us    -9.34%     0.410 us    0.368 us   -10.24%            1          1         +0   b
    1.657 us    1.506 us    -9.11%     0.890 us    0.800 us   -10.11%            1          1         +0   c
    0.920 us    0.789 us   -14.24%     0.920 us    0.789 us   -14.24%            1          1         +0   __cxa_atexit
    0.767 us    0.706 us    -7.95%     0.767 us    0.706 us    -7.95%            1          1         +0   getpid
\f[R]
.fi
.SH FIELDS
.PP
The uftrace allows user to customize the report output with a couple of
fields.
By default it uses total, self and call fields, but you can use other
fields in any order like:
.IP
.nf
\f[C]
$ uftrace report -f total,total-max,self-min,call
Total time   Total max    Self min       Calls  Function
==========  ==========  ==========  ==========  ====================
 97.234 us   36.033 us    1.073 us           3  lib_a
 50.552 us   26.690 us    2.828 us           2  lib_b
 46.806 us   46.806 us    3.290 us           1  main
 43.516 us   43.516 us    7.483 us           1  foo
 32.010 us   20.847 us    9.684 us           2  lib_c
\f[R]
.fi
.PP
Each field can be used as sort key:
.IP
.nf
\f[C]
$ uftrace report -f total,total-max,self-min,call -s call
Total time   Total max    Self min       Calls  Function
==========  ==========  ==========  ==========  ====================
 97.234 us   36.033 us    1.073 us           3  lib_a
 50.552 us   26.690 us    2.828 us           2  lib_b
 32.010 us   20.847 us    9.684 us           2  lib_c
 43.516 us   43.516 us    7.483 us           1  foo
 46.806 us   46.806 us    3.290 us           1  main

$ uftrace report -f total,total-max,self-min,total-min,call -s self-min,total-min
Total time   Total max    Self min   Total min       Calls  Function
==========  ==========  ==========  ==========  ==========  ====================
 32.010 us   20.847 us    9.684 us   11.163 us           2  lib_c
 43.516 us   43.516 us    7.483 us   43.516 us           1  foo
 46.806 us   46.806 us    3.290 us   46.806 us           1  main
 50.552 us   26.690 us    2.828 us   23.862 us           2  lib_b
 97.234 us   36.033 us    1.073 us   27.763 us           3  lib_a
\f[R]
.fi
.PP
Each field can be used with \[en]diff option:
.IP
.nf
\f[C]
$ uftrace report --diff uftrace.data.old -f total,total-min
#
# uftrace diff
#  [0] base: uftrace.data       (from uftrace record test/t-lib)
#  [1] diff: uftrace.data.old   (from uftrace record test/t-lib)
#
 Total time     Total min   Function
===========   ===========   ====================
 +34.560 us     +9.884 us   lib_a
 +18.086 us     +8.517 us   lib_b
 +16.887 us    +16.887 us   main
 +15.479 us    +15.479 us   foo
 +10.600 us     +3.127 us   lib_c

$ uftrace report --diff uftrace.data.old -f total,total-min,self-avg --diff-policy full
#
# uftrace diff
#  [0] base: uftrace.data           (from uftrace record --srcline test/t-lib)
#  [1] diff: uftrace.data.old   (from uftrace record --srcline test/t-lib)
#
                  Total time (diff)                      Total min (diff)                       Self avg (diff)   Function
===================================   ===================================   ===================================   ====================
 14.616 us   13.796 us    +0.820 us     4.146 us    3.823 us    +0.323 us     0.443 us    0.459 us    -0.016 us   lib_a
  6.529 us    5.957 us    +0.572 us     6.529 us    5.957 us    +0.572 us     0.436 us    0.356 us    +0.080 us   main
  7.700 us    7.173 us    +0.527 us     3.677 us    3.426 us    +0.251 us     0.365 us    0.363 us    +0.002 us   lib_b
  6.093 us    5.601 us    +0.492 us     6.093 us    5.601 us    +0.492 us     0.741 us    0.476 us    +0.265 us   foo
  5.638 us    5.208 us    +0.430 us     2.346 us    2.187 us    +0.159 us     1.646 us    1.510 us    +0.136 us   lib_c
\f[R]
.fi
.PP
Each field has following meaning:
.IP \[bu] 2
total: total time of each function.
.IP \[bu] 2
total-avg: average of total time of each function.
.IP \[bu] 2
total-min: min of total time of each function.
.IP \[bu] 2
total-max: max of total time of each function.
.IP \[bu] 2
self: self time of each function.
.IP \[bu] 2
self-avg: average of self time of each function.
.IP \[bu] 2
self-min: min of self time of each function.
.IP \[bu] 2
self-max: max of self time of each function.
.IP \[bu] 2
call: called count of each function.
.PP
The default value is `total,self,call'.
If given field name starts with \[lq]+\[rq], then it\[cq]ll be appended
to the default fields.
So \[lq]-f +total-avg\[rq] is as same as \[lq]-f
total,self,call,total-avg\[rq].
And it also accepts a special field name of `none' which disables the
field display and shows function output only.
.SH TASK FIELDS
.IP \[bu] 2
total: total time of each task.
.IP \[bu] 2
self: self time of each task.
.IP \[bu] 2
func: number of functions in the task.
.IP \[bu] 2
tid: task ID.
.PP
The default value is `total,self,func,tid'.
See \f[I]FIELDS\f[R] for field usage.
.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-tui\f[R](1)
.SH AUTHORS
Namhyung Kim <namhyung@gmail.com>.