lttng-ust-cyg-profile(3)

1LTTNG-UST-CYG-PRO(3)             LTTng Manual             LTTNG-UST-CYG-PRO(3)
2
3
4

NAME

6       lttng-ust-cyg-profile - Function tracing (LTTng-UST helper)
7

SYNOPSIS

9       Compile your application with compiler option -finstrument-functions.
10
11       Launch your application by preloading liblttng-ust-cyg-profile-fast.so
12       for fast function tracing:
13
14       $ LD_PRELOAD=liblttng-ust-cyg-profile-fast.so my-app
15
16       Launch your application by preloading liblttng-ust-cyg-profile.so for
17       slower, more verbose function tracing:
18
19       $ LD_PRELOAD=liblttng-ust-cyg-profile.so my-app
20

DESCRIPTION

22       When the liblttng-ust-cyg-profile.so or the liblttng-ust-cyg-profile-
23       fast.so library is preloaded before a given application starts, all
24       function entry and return points are traced by LTTng-UST (see lttng-
25       ust(3)), provided said application was compiled with the -finstrument-
26       functions compiler option.
27
28       See lttng(1) to learn more about how to control LTTng tracing sessions.
29
30       Function tracing with LTTng-UST comes in two flavors, each one
31       providing a different trade-off between performance and robustness:
32
33       liblttng-ust-cyg-profile-fast.so
34           This is a lightweight variant that should only be used where it can
35           be guaranteed that the complete event stream is recorded without
36           any missing events. Any kind of duplicate information is left out.
37
38           At each function entry, the address of the called function is
39           recorded in an LTTng-UST event. Function exits are recorded as
40           another, empty LTTng-UST event.
41
42           See the Fast function tracing section below for the complete list
43           of emitted events and their fields.
44
45       liblttng-ust-cyg-profile.so
46           This is a more robust variant which also works for use cases where
47           events might get discarded, or not recorded from application
48           startup. In these cases, the trace analyzer needs extra information
49           to be able to reconstruct the program flow.
50
51           At each function entry and exit, the address of the called function
52           and the call site address are recorded in an LTTng-UST event.
53
54           See the Verbose function tracing section below for the complete
55           list of emitted events and their fields.
56
57   Usage
58       To use LTTng-UST function tracing, you need to make sure the sources of
59       your application are compiled with the -finstrument-functions compiler
60       option.
61
62       It might be necessary to limit the number of source files where this
63       option is used to prevent excessive amount of trace data to be
64       generated at run time. Usually, there are additional compiler flags
65       that allow you to specify a more fine-grained selection of function
66       instrumentation.
67
68       For each instrumented function, the executable will contain calls to
69       profiling function hooks (after function entry, named
70       __cyg_profile_func_enter(), and just before function exit, named
71       __cyg_profile_func_exit()).
72
73       By preloading (using the LD_PRELOAD environment variable) one of the
74       provided shared libraries, these profiling hooks get defined to emit
75       LTTng events (as described below).
76
77           Note
78           Using this feature can result in a massive amount of trace data to
79           be generated by the instrumented application. Application run time
80           is also considerably affected. Be careful on systems with limited
81           resources.
82
83   Fast function tracing
84       The following LTTng-UST events are available when using liblttng-ust-
85       cyg-profile-fast.so. Their log level is set to
86       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION.
87
88       lttng_ust_cyg_profile_fast:func_entry
89           Emitted when an application function is entered, or more
90           specifically, when __cyg_profile_func_enter() is called.
91
92           Fields:
93
94           ┌───────────┬───────────────────┐
95           │Field name │ Description       │
96           ├───────────┼───────────────────┤
97           │func_addr  │ Function address. │
98           └───────────┴───────────────────┘
99
100       lttng_ust_cyg_profile_fast:func_exit
101           Emitted when an application function returns, or more specifically,
102           when __cyg_profile_func_exit() is called.
103
104           This event has no fields. Since the liblttng-ust-cyg-profile-
105           fast.so library should only be used when it can be guaranteed that
106           the complete event stream is recorded without any missing events, a
107           per-thread, stack-based approach can be used on the trace analyzer
108           side to match function entry and return events.
109
110   Verbose function tracing
111       The following LTTng-UST events are available when using liblttng-ust-
112       cyg-profile.so. Their log level is set to
113       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION.
114
115       lttng_ust_cyg_profile:func_entry
116           Emitted when an application function is entered, or more
117           specifically, when __cyg_profile_func_enter() is called.
118
119           Fields:
120
121           ┌───────────┬─────────────────────────┐
122           │Field name │ Description             │
123           ├───────────┼─────────────────────────┤
124           │func_addr  │ Function address.       │
125           ├───────────┼─────────────────────────┤
126           │call_site  │ Address from which this │
127           │           │ function was called.    │
128           └───────────┴─────────────────────────┘
129
130       lttng_ust_cyg_profile:func_exit
131           Emitted when an application function returns, or more specifically,
132           when __cyg_profile_func_exit() is called.
133
134           Fields:
135
136           ┌───────────┬─────────────────────────┐
137           │Field name │ Description             │
138           ├───────────┼─────────────────────────┤
139           │func_addr  │ Function address.       │
140           ├───────────┼─────────────────────────┤
141           │call_site  │ Address from which this │
142           │           │ function was called.    │
143           └───────────┴─────────────────────────┘
144

BUGS

146       If you encounter any issue or usability problem, please report it on
147       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
148

RESOURCES

150       •   LTTng project website <http://lttng.org>
151
152       •   LTTng documentation <http://lttng.org/docs>
153
154       •   Git repositories <http://git.lttng.org>
155
156       •   GitHub organization <http://github.com/lttng>
157
158       •   Continuous integration <http://ci.lttng.org/>
159
160       •   Mailing list <http://lists.lttng.org> for support and development:
161           lttng-dev@lists.lttng.org
162
163       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
164

COPYRIGHTS

166       This library is part of the LTTng-UST project.
167
168       This library is distributed under the GNU Lesser General Public
169       License, version 2.1 <http://www.gnu.org/licenses/old-
170       licenses/lgpl-2.1.en.html>. See the for more details.
171

THANKS

173       Thanks to Ericsson for funding this work, providing real-life use
174       cases, and testing.
175
176       Special thanks to Michel Dagenais and the DORSAL laboratory
177       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
178       the LTTng journey.
179

AUTHORS

181       LTTng-UST was originally written by Mathieu Desnoyers, with additional
182       contributions from various other people. It is currently maintained by
183       Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
184