doc/man/lttng-ust-cyg-profile.3

   1 .TH "LTTNG-UST-CYG-PROFILE" "3" "March 26, 2013" "" ""
   2 .SH "NAME"
   3 lttng-ust-cyg-profile \(em LTTng UST 2.x Function Tracing
   4 .SH "SYNOPSIS"
   5 Compile the application source code with option \fB-finstrument-functions\fP
   6 and launch your application either with:
   7 .TP
   8 \fBLD_PRELOAD=liblttng-ust-cyg-profile-fast.so\fP appname
   9 .PP
  10 or (to use verbose function tracing)
  11 .TP
  12 \fBLD_PRELOAD=liblttng-ust-cyg-profile.so\fP appname
  13 .PP
  14 All events emitted for function tracing are provided on loglevel
  15 TRACE_DEBUG_FUNCTION. The following command can be used to add
  16 function tracing events in your trace session:
  17 .TP
  18 .B lttng enable-event -u -a --loglevel-only TRACE_DEBUG_FUNCTION
  19 .SH "DESCRIPTION"
  20 For compilers that provide code generation option
  21 \fB-finstrument-functions\fP (e.g. GCC and LLVM/Clang) LTTng-UST provides
  22 shared libraries that allow users to trace the function flow of their
  23 applications.
  24
  25 Function tracing comes in two flavors (each providing different trade-offs):
  26 .IP liblttng-ust-cyg-profile-fast.so
  27 This is a lightweight variant that should only be used where it can be
  28 guaranteed that the complete event stream is recorded without any missing
  29 events. Any kind of duplicate information is left out.
  30
  31 At each function entry the address of the called function is recored as
  32 lttng_ust_cyg_profile_fast:func_entry. Function exit is recorded as
  33 lttng_ust_cyg_profile_fast:func_exit (without any field data).
  34
  35 .IP liblttng-ust-cyg-profile.so
  36 This is a more robust variant which also works for use-cases where events
  37 might get discarded or not recorded from application startup. In these cases
  38 the trace analyzer needs extra information to be able to reconstruct the
  39 program flow.
  40
  41 For each function entry and exit the address of the called function and the
  42 call site address are recorded as lttng_ust_cyg_profile:func_entry and
  43 lttng_ust_cyg_profile:func_exit.
  44 .SH "USAGE"
  45 To use function tracing you need to make sure the sources of your application
  46 are compiled with \-finstrument\-functions. It might be necessary to limit
  47 the number of source files where this option is used to prevent excessive
  48 amount of trace data to be generated during run time. Usually there are
  49 additional compiler flags that allow you to specify more fine grained selection
  50 of function instrumentation.
  51
  52 For each instrumented function the executable will contain calls to profiling
  53 function hooks (after function entry and just before function exit).
  54
  55 By preloading (LD_PRELOAD) one of the provided shared libraries, these
  56 profiling hooks get defined to emit LTTng events (as described above).
  57
  58 Using this feature can result in massive amount trace data to be generated
  59 by the instrumented application. Application runtime is also considerably
  60 affected. Be careful on systems with limited resources.
  61 .SH "SEE ALSO"
  62 lttng-ust(3), lttng(1), gcc(1), ld.so(8)
  63 .SH "BUGS"
  64 If you encounter any issues or usability problem, please report it on
  65 our mailing list <lttng-dev@lists.lttng.org> to help improve this
  66 project.
  67 .SH "CREDITS"
  68 liblttng-ust is distributed under the GNU Lesser General Public License
  69 version 2.1. The headers are distributed under the MIT license.
  70
  71 See http://lttng.org for more information on the LTTng project.
  72
  73 Mailing list for support and development: <lttng-dev@lists.lttng.org>.
  74
  75 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
  76 .SH "AUTHORS"
  77 liblttng-ust was originally written by Mathieu Desnoyers, with additional
  78 contributions from various other people. It is currently maintained by
  79 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.