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)