NAME

       lttng-ust-cyg-profile — LTTng UST 2.x Function Tracing

SYNOPSIS

       Compile the application source code with option -finstrument-functions and launch your application either
       with:

       LD_PRELOAD=liblttng-ust-cyg-profile-fast.so appname

       or (to use verbose function tracing)

       LD_PRELOAD=liblttng-ust-cyg-profile.so appname

       All events emitted for function tracing are provided  on  loglevel  TRACE_DEBUG_FUNCTION.  The  following
       command can be used to add function tracing events in your trace session:

       lttng enable-event -u -a --loglevel-only TRACE_DEBUG_FUNCTION

DESCRIPTION

       For compilers that provide code generation option -finstrument-functions (e.g. GCC and LLVM/Clang) LTTng-
       UST provides shared libraries that allow users to trace the function flow of their applications.

       Function tracing comes in two flavors (each providing different trade-offs):

       liblttng-ust-cyg-profile-fast.so
              This is a lightweight variant that should only be  used  where  it  can  be  guaranteed  that  the
              complete event stream is recorded without any missing events. Any kind of duplicate information is
              left out.

              At   each   function   entry   the   address   of   the   called   function    is    recored    as
              lttng_ust_cyg_profile_fast:func_entry.        Function       exit       is       recorded       as
              lttng_ust_cyg_profile_fast:func_exit (without any field data).

       liblttng-ust-cyg-profile.so
              This is a more robust variant which also works for use-cases where events might get  discarded  or
              not  recorded  from application startup. In these cases the trace analyzer needs extra information
              to be able to reconstruct the program flow.

              For each function entry and exit the address of the called function and the call site address  are
              recorded as lttng_ust_cyg_profile:func_entry and lttng_ust_cyg_profile:func_exit.

USAGE

       To  use  function  tracing  you  need  to  make  sure  the  sources of your application are compiled with
       -finstrument-functions. It might be necessary to limit the number of source files where  this  option  is
       used  to  prevent  excessive  amount  of  trace  data  to be generated during run time. Usually there are
       additional  compiler  flags  that  allow  you  to  specify  more  fine  grained  selection  of   function
       instrumentation.

       For  each  instrumented  function  the  executable  will contain calls to profiling function hooks (after
       function entry and just before function exit).

       By preloading (LD_PRELOAD) one of the provided shared libraries, these profiling  hooks  get  defined  to
       emit LTTng events (as described above).

       Using  this  feature  can  result  in  massive  amount  trace  data  to  be generated by the instrumented
       application. Application runtime is also considerably  affected.  Be  careful  on  systems  with  limited
       resources.

SEE ALSO

       lttng-ust(3), lttng(1), gcc(1), ld.so(8)

BUGS

       If  you  encounter  any  issues  or  usability  problem,  please  report  it  on our mailing list <lttng-
       dev@lists.lttng.org> to help improve this project.

CREDITS

       liblttng-ust is distributed under the GNU Lesser General Public License  version  2.1.  The  headers  are
       distributed under the MIT license.

       See http://lttng.org for more information on the LTTng project.

       Mailing list for support and development: <lttng-dev@lists.lttng.org>.

       You can find us on IRC server irc.oftc.net (OFTC) in #lttng.

AUTHORS

       liblttng-ust  was  originally  written  by  Mathieu Desnoyers, with additional contributions from various
       other people. It is currently maintained by Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.

                                                 March 26, 2013                         LTTNG-UST-CYG-PROFILE(3)