1 // SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
2 // SPDX-License-Identifier: CC-BY-4.0
4 lttng-ust-cyg-profile(3)
5 ========================
11 lttng-ust-cyg-profile - Function tracing (LTTng-UST helper)
16 Compile your application with compiler option
17 nloption:-finstrument-functions.
19 Launch your application by preloading
20 `liblttng-ust-cyg-profile-fast.so` for fast function tracing:
24 $ *LD_PRELOAD=liblttng-ust-cyg-profile-fast.so* my-app
26 Launch your application by preloading
27 `liblttng-ust-cyg-profile.so` for slower, more verbose function
32 $ *LD_PRELOAD=liblttng-ust-cyg-profile.so* my-app
37 When the `liblttng-ust-cyg-profile.so` or the
38 `liblttng-ust-cyg-profile-fast.so` library is preloaded before a given
39 application starts, all function entry and return points are traced by
40 LTTng-UST (see man:lttng-ust(3)), provided said application was compiled
41 with the nloption:-finstrument-functions compiler option.
43 See man:lttng(1) to learn more about how to control LTTng tracing
46 Function tracing with LTTng-UST comes in two flavors, each one
47 providing a different trade-off between performance and robustness:
49 `liblttng-ust-cyg-profile-fast.so`::
50 This is a lightweight variant that should only be used where it can
51 be _guaranteed_ that the complete event stream is recorded without
52 any missing events. Any kind of duplicate information is left out.
54 At each function entry, the address of the called function is
55 recorded in an LTTng-UST event. Function exits are recorded as
56 another, empty LTTng-UST event.
58 See the <<ftrace-fast,Fast function tracing>> section below for the
59 complete list of emitted events and their fields.
61 `liblttng-ust-cyg-profile.so`::
62 This is a more robust variant which also works for use cases where
63 events might get discarded, or not recorded from application
64 startup. In these cases, the trace analyzer needs extra
65 information to be able to reconstruct the program flow.
67 At each function entry _and_ exit, the address of the called
68 function _and_ the call site address are recorded in an LTTng-UST
71 See the <<ftrace-verbose,Verbose function tracing>> section below for
72 the complete list of emitted events and their fields.
77 To use LTTng-UST function tracing, you need to make sure the sources of
78 your application are compiled with the nloption:-finstrument-functions
81 It might be necessary to limit the number of source files where this
82 option is used to prevent excessive amount of trace data to be generated
83 at run time. Usually, there are additional compiler flags that allow
84 you to specify a more fine-grained selection of function
87 For each instrumented function, the executable will contain calls to
88 profiling function hooks (after function entry, named `__cyg_profile_func_enter()`,
89 and just before function exit, named `__cyg_profile_func_exit()`).
91 By preloading (using the `LD_PRELOAD` environment variable) one of the
92 provided shared libraries, these profiling hooks get defined to emit
93 LTTng events (as described below).
95 NOTE: Using this feature can result in a *massive amount* of trace data
96 to be generated by the instrumented application. Application run time is
97 also considerably affected. Be careful on systems with limited
102 Fast function tracing
103 ~~~~~~~~~~~~~~~~~~~~~
104 The following LTTng-UST events are available when using
105 `liblttng-ust-cyg-profile-fast.so`. Their log level is set to
106 `LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION`.
108 `lttng_ust_cyg_profile_fast:func_entry`::
109 Emitted when an application function is entered, or more
110 specifically, when `__cyg_profile_func_enter()` is called.
116 |Field name |Description
122 `lttng_ust_cyg_profile_fast:func_exit`::
123 Emitted when an application function returns, or more
124 specifically, when `__cyg_profile_func_exit()` is called.
126 This event has no fields. Since the `liblttng-ust-cyg-profile-fast.so`
127 library should only be used when it can be guaranteed that the complete
128 event stream is recorded without any missing events, a per-thread,
129 stack-based approach can be used on the trace analyzer side to match
130 function entry and return events.
134 Verbose function tracing
135 ~~~~~~~~~~~~~~~~~~~~~~~~
136 The following LTTng-UST events are available when using
137 `liblttng-ust-cyg-profile.so`. Their log level is set to
138 `LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION`.
140 `lttng_ust_cyg_profile:func_entry`::
141 Emitted when an application function is entered, or more
142 specifically, when `__cyg_profile_func_enter()` is called.
148 |Field name |Description
154 |Address from which this function was called.
157 `lttng_ust_cyg_profile:func_exit`::
158 Emitted when an application function returns, or more
159 specifically, when `__cyg_profile_func_exit()` is called.
165 |Field name |Description
171 |Address from which this function was called.
175 include::common-footer.txt[]
177 include::common-copyrights.txt[]
179 include::common-authors.txt[]