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