1LTTNG-UST-DL(3) LTTng Manual LTTNG-UST-DL(3)
2
3
4
6 lttng-ust-cyg-profile - Function tracing (LTTng-UST helper)
7
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
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 TRACE_DEBUG_FUNCTION.
86
87 lttng_ust_cyg_profile_fast:func_entry
88 Emitted when an application function is entered, or more
89 specifically, when __cyg_profile_func_enter() is called.
90
91 Fields:
92
93 ┌───────────┬───────────────────┐
94 │Field name │ Description │
95 ├───────────┼───────────────────┤
96 │func_addr │ Function address. │
97 └───────────┴───────────────────┘
98
99 lttng_ust_cyg_profile_fast:func_exit
100 Emitted when an application function returns, or more specifically,
101 when __cyg_profile_func_exit() is called.
102
103 This event has no fields. Since the liblttng-ust-cyg-profile-
104 fast.so library should only be used when it can be guaranteed that
105 the complete event stream is recorded without any missing events, a
106 per-thread, stack-based approach can be used on the trace analyzer
107 side to match function entry and return events.
108
109 Verbose function tracing
110 The following LTTng-UST events are available when using liblttng-ust-
111 cyg-profile.so. Their log level is set to TRACE_DEBUG_FUNCTION.
112
113 lttng_ust_cyg_profile:func_entry
114 Emitted when an application function is entered, or more
115 specifically, when __cyg_profile_func_enter() is called.
116
117 Fields:
118
119 ┌───────────┬─────────────────────────┐
120 │Field name │ Description │
121 ├───────────┼─────────────────────────┤
122 │func_addr │ Function address. │
123 ├───────────┼─────────────────────────┤
124 │call_site │ Address from which this │
125 │ │ function was called. │
126 └───────────┴─────────────────────────┘
127
128 lttng_ust_cyg_profile:func_exit
129 Emitted when an application function returns, or more specifically,
130 when __cyg_profile_func_exit() is called.
131
132 Fields:
133
134 ┌───────────┬─────────────────────────┐
135 │Field name │ Description │
136 ├───────────┼─────────────────────────┤
137 │func_addr │ Function address. │
138 ├───────────┼─────────────────────────┤
139 │call_site │ Address from which this │
140 │ │ function was called. │
141 └───────────┴─────────────────────────┘
142
144 If you encounter any issue or usability problem, please report it on
145 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
146
148 · LTTng project website <http://lttng.org>
149
150 · LTTng documentation <http://lttng.org/docs>
151
152 · Git repositories <http://git.lttng.org>
153
154 · GitHub organization <http://github.com/lttng>
155
156 · Continuous integration <http://ci.lttng.org/>
157
158 · Mailing list <http://lists.lttng.org> for support and development:
159 lttng-dev@lists.lttng.org
160
161 · IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
162
164 This library is part of the LTTng-UST project.
165
166 This library is distributed under the GNU Lesser General Public
167 License, version 2.1 <http://www.gnu.org/licenses/old-
168 licenses/lgpl-2.1.en.html>. See the COPYING
169 <https://github.com/lttng/lttng-ust/blob/v2.10.6/COPYING> file for more
170 details.
171
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
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
186 lttng-ust(3), lttng(1), gcc(1), ld.so(8)
187
188
189
190LTTng 2.10.6 10/17/2019 LTTNG-UST-DL(3)