8 lttng-ust-cyg-profile - Function tracing (LTTng-UST helper)
13 Compile your application with compiler option
14 nloption:-finstrument-functions.
16 Launch your application by preloading
17 `liblttng-ust-cyg-profile-fast.so` for fast function tracing:
21 $ *LD_PRELOAD=liblttng-ust-cyg-profile-fast.so* my-app
23 Launch your application by preloading
24 `liblttng-ust-cyg-profile.so` for slower, more verbose function
29 $ *LD_PRELOAD=liblttng-ust-cyg-profile.so* my-app
34 When the `liblttng-ust-cyg-profile.so` or the
35 `liblttng-ust-cyg-profile-fast.so` library is preloaded before a given
36 application starts, all function entry and return points are traced by
37 LTTng-UST (see man:lttng-ust(3)), provided said application was compiled
38 with the nloption:-finstrument-functions compiler option.
40 See man:lttng(1) to learn more about how to control LTTng tracing
43 Function tracing with LTTng-UST comes in two flavors, each one
44 providing a different trade-off between performance and robustness:
46 `liblttng-ust-cyg-profile-fast.so`::
47 This is a lightweight variant that should only be used where it can
48 be _guaranteed_ that the complete event stream is recorded without
49 any missing events. Any kind of duplicate information is left out.
51 At each function entry, the address of the called function is
52 recorded in an LTTng-UST event. Function exits are recorded as
53 another, empty LTTng-UST event.
55 See the <<ftrace-fast,Fast function tracing>> section below for the
56 complete list of emitted events and their fields.
58 `liblttng-ust-cyg-profile.so`::
59 This is a more robust variant which also works for use cases where
60 events might get discarded, or not recorded from application
61 startup. In these cases, the trace analyzer needs extra
62 information to be able to reconstruct the program flow.
64 At each function entry _and_ exit, the address of the called
65 function _and_ the call site address are recorded in an LTTng-UST
68 See the <<ftrace-verbose,Verbose function tracing>> section below for
69 the complete list of emitted events and their fields.
74 To use LTTng-UST function tracing, you need to make sure the sources of
75 your application are compiled with the nloption:-finstrument-functions
78 It might be necessary to limit the number of source files where this
79 option is used to prevent excessive amount of trace data to be generated
80 at run time. Usually, there are additional compiler flags that allow
81 you to specify a more fine-grained selection of function
84 For each instrumented function, the executable will contain calls to
85 profiling function hooks (after function entry, named `__cyg_profile_func_enter()`,
86 and just before function exit, named `__cyg_profile_func_exit()`).
88 By preloading (using the `LD_PRELOAD` environment variable) one of the
89 provided shared libraries, these profiling hooks get defined to emit
90 LTTng events (as described below).
92 NOTE: Using this feature can result in a *massive amount* of trace data
93 to be generated by the instrumented application. Application run time is
94 also considerably affected. Be careful on systems with limited
100 ~~~~~~~~~~~~~~~~~~~~~
101 The following LTTng-UST events are available when using
102 `liblttng-ust-cyg-profile-fast.so`. Their log level is set to
103 `TRACE_DEBUG_FUNCTION`.
105 `lttng_ust_cyg_profile_fast:func_entry`::
106 Emitted when an application function is entered, or more
107 specifically, when `__cyg_profile_func_enter()` is called.
113 |Field name |Description
119 `lttng_ust_cyg_profile_fast:func_exit`::
120 Emitted when an application function returns, or more
121 specifically, when `__cyg_profile_func_exit()` is called.
123 This event has no fields. Since the `liblttng-ust-cyg-profile-fast.so`
124 library should only be used when it can be guaranteed that the complete
125 event stream is recorded without any missing events, a per-thread,
126 stack-based approach can be used on the trace analyzer side to match
127 function entry and return events.
131 Verbose function tracing
132 ~~~~~~~~~~~~~~~~~~~~~~~~
133 The following LTTng-UST events are available when using
134 `liblttng-ust-cyg-profile.so`. Their log level is set to
135 `TRACE_DEBUG_FUNCTION`.
137 `lttng_ust_cyg_profile:func_entry`::
138 Emitted when an application function is entered, or more
139 specifically, when `__cyg_profile_func_enter()` is called.
145 |Field name |Description
151 |Address from which this function was called.
154 `lttng_ust_cyg_profile:func_exit`::
155 Emitted when an application function returns, or more
156 specifically, when `__cyg_profile_func_exit()` is called.
162 |Field name |Description
168 |Address from which this function was called.
172 include::common-footer.txt[]
174 include::common-copyrights.txt[]
176 include::common-authors.txt[]