Commit | Line | Data |
---|---|---|
d1eaa4d7 PW |
1 | .TH "LTTNG-UST-CYG-PROFILE" "3" "March 26, 2013" "" "" |
2 | .SH "NAME" | |
3 | lttng-ust-cyg-profile \(em LTTng UST 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>. |