Provided by: uftrace_0.9.0-1_amd64 bug

NAME

       uftrace-replay - Print recorded function trace

SYNOPSIS

       uftrace replay [options]

DESCRIPTION

       This  command  prints trace data recorded using the uftrace-record(1) command.  The traced
       functions are printed like a C program in time order.

OPTIONS

       --flat Print flat format rather than C-like format.  This is  usually  for  debugging  and
              testing purpose.

       -F FUNC, --filter=FUNC
              Set  filter  to  trace  selected functions only.  This option can be used more than
              once.  See FILTERS.

       -N FUNC, --notrace=FUNC
              Set filter not to trace selected functions  (or  the  functions  called  underneath
              them).  This option can be used more than once.  See FILTERS.

       -T TRG, --trigger=TRG
              Set  trigger  on  selected functions.  This option can be used more than once.  See
              TRIGGERS.

       -t TIME, --time-filter=TIME
              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.

       --tid=TID[,TID,...]
              Only print functions called by the given threads.  To see the list  of  threads  in
              the  data  file, you can use uftrace report --threads or uftrace info.  This option
              can also be used more than once.

       -D DEPTH, --depth DEPTH
              Set trace limit in nesting level.

       -f FIELD, --output-fields=FIELD
              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 FIELDS.

       -r RANGE, --time-range=RANGE
              Only   show   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.

       --disable
              Start  uftrace  with  tracing  disabled.   This is only meaningful when used with a
              trace_on trigger.

       --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.

       –column-view
              Show each task in separate column.  This makes easy  to  distinguish  functions  in
              different tasks.

       –column-offset=DEPTH
              When  --column-view  option  is  used,  this  option specifies the amount of offset
              between each task.  Default is 8.

       –task-newline
              Interleave a new line when  task  is  changed.   This  makes  easy  to  distinguish
              functions in different tasks.

       –no-comment
              Do not show comments of returned functions.

       -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
              -N .@kernel to filter out all kernel functions (for the regex match).

       --kernel-full
              Show all kernel functions and events occurred  outside  of  user  functions.   This
              option is the inverse of --kernel-skip-out.

       --kernel-skip-out
              Do  not  show  kernel  functions  called outside of user functions.  This option is
              deprecated and set to true by default.

       --kernel-only
              Show kernel functions only without user functions.

       --event-full
              Show all (user) events outside of user functions.

       --no-event
              Do not show any events.

       --libname
              Show libname name along with function name.

       –match=TYPE
              Use pattern match using TYPE.  Possible types  are  regex  and  glob.   Default  is
              regex.

FILTERS

       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/--filter and an opt-out
       filter  with  -N/--notrace.   These filters can be applied either at record time or replay
       time.

       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.

       For example, consider a simple program which calls a(), b() and c() in turn.

              $ 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

       Normally uftrace replay will show all the functions from main() to 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 */

       But when the -F b filter option is used, it will not show main() or a() but only  b()  and
       c().  Note that the filter was set on uftrace replay, not at record time.

              $ uftrace record ./abc
              $ uftrace replay -F b
              # DURATION    TID     FUNCTION
                          [ 1234] | b() {
                 3.880 us [ 1234] |   c();
                 5.475 us [ 1234] | } /* b */

       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.

       In  the  above  example,  you can omit the function b() and all calls it makes with the -N
       option.

              $ 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 */

       In addition, you can limit the print nesting level with -D option.

              $ 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 */

       In the above example, uftrace only prints functions up to a depth of 3, so  leaf  function
       c() was omitted.  Note that the -D option also works with -F.

       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  -t/--time-filter  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:

              $ 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 */

       You can also see replay output with different time threshold for the same recorded data.

              $ 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 */

       In  addition, The -r 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.

              $ 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();

       You can also set triggers on filtered functions.  See TRIGGERS section below for details.

TRIGGERS

       The uftrace tool supports triggering actions on selected function calls  with  or  without
       filters.   Currently supported triggers are depth, backtrace, trace_on and trace_off.  The
       BNF for trigger specifications is like below:

              <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"

       The depth 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 backtrace trigger
       is used to print a stack backtrace at replay time.

       The color trigger is to change the color of the function in replay output.  The  supported
       colors are red, green, blue, yellow, magenta, cyan, bold, and gray.

       The  following  example shows how triggers work.  We set a filter on function b() with the
       backtrace action and change the maximum filter depth under b() to 2.

              $ uftrace record ./abc
              $ uftrace replay -T 'b@filter,backtrace,depth=2'
              # DURATION    TID     FUNCTION
                backtrace [ 1234] | /* [ 0] main */
                backtrace [ 1234] | /* [ 1] a */
                          [ 1234] | b {
                 3.880 us [ 1234] |   c();
                 5.475 us [ 1234] | } /* b */

       The traceon and traceoff actions (the _  can  be  omitted  from  trace_on  and  trace_off)
       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
       uftrace record.

       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.

       The `filter' and `notrace' triggers have same effect as -F/–filter and -N/–notrace options
       respectively.

FIELDS

       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:

              $ 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 */

       Each field has following meaning:

       · tid: task id (obtained by gettid(2))

       · duration: function execution time

       · time: timestamp at the execution

       · delta: difference between two timestamp in a task

       · elapsed: elapsed time from the first timestamp

       · addr: address of the function

       · task: task name (comm)

       · module: library or executable name of the function

       The  default  value is `duration,tid'.  If given field name starts with “+”, then it'll be
       appended to the default fields.  So “-f +time” is as same as “-f duration,tid,time”.   And
       it  also accepts a special field name of `none' which disables the field display and shows
       function output only.

SEE ALSO

       uftrace(1), uftrace-record(1), uftrace-report(1), uftrace-info(1)

AUTHORS

       Namhyung Kim <namhyung@gmail.com>.