Commit | Line | Data |
---|---|---|
53f7d0d7 MJ |
1 | // SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com> |
2 | // SPDX-License-Identifier: CC-BY-4.0 | |
3 | // | |
5b1163c6 PP |
4 | lttng-ust-cyg-profile(3) |
5 | ======================== | |
4ddbd0b7 PP |
6 | :object-type: library |
7 | ||
8 | ||
9 | NAME | |
10 | ---- | |
11 | lttng-ust-cyg-profile - Function tracing (LTTng-UST helper) | |
12 | ||
13 | ||
14 | SYNOPSIS | |
15 | -------- | |
16 | Compile your application with compiler option | |
17 | nloption:-finstrument-functions. | |
18 | ||
19 | Launch your application by preloading | |
20 | `liblttng-ust-cyg-profile-fast.so` for fast function tracing: | |
21 | ||
22 | [role="term"] | |
23 | [verse] | |
636cf2a0 | 24 | $ *LD_PRELOAD=liblttng-ust-cyg-profile-fast.so* my-app |
4ddbd0b7 PP |
25 | |
26 | Launch your application by preloading | |
27 | `liblttng-ust-cyg-profile.so` for slower, more verbose function | |
28 | tracing: | |
29 | ||
30 | [role="term"] | |
31 | [verse] | |
636cf2a0 | 32 | $ *LD_PRELOAD=liblttng-ust-cyg-profile.so* my-app |
4ddbd0b7 PP |
33 | |
34 | ||
35 | DESCRIPTION | |
36 | ----------- | |
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. | |
42 | ||
43 | See man:lttng(1) to learn more about how to control LTTng tracing | |
44 | sessions. | |
45 | ||
46 | Function tracing with LTTng-UST comes in two flavors, each one | |
47 | providing a different trade-off between performance and robustness: | |
48 | ||
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. | |
53 | + | |
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. | |
57 | + | |
58 | See the <<ftrace-fast,Fast function tracing>> section below for the | |
59 | complete list of emitted events and their fields. | |
60 | ||
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. | |
66 | + | |
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 | |
69 | event. | |
70 | + | |
71 | See the <<ftrace-verbose,Verbose function tracing>> section below for | |
72 | the complete list of emitted events and their fields. | |
73 | ||
74 | ||
75 | Usage | |
76 | ~~~~~ | |
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 | |
79 | compiler option. | |
80 | ||
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 | |
85 | instrumentation. | |
86 | ||
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()`). | |
90 | ||
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). | |
94 | ||
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 | |
98 | resources. | |
99 | ||
100 | ||
101 | [[ftrace-fast]] | |
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 | |
5b1163c6 | 106 | `LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION`. |
4ddbd0b7 PP |
107 | |
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. | |
111 | + | |
112 | Fields: | |
113 | + | |
114 | [options="header"] | |
8902dadc PP |
115 | |=== |
116 | |Field name |Description | |
117 | ||
118 | |`func_addr` | |
d01f365a | 119 | |Function address. |
8902dadc | 120 | |=== |
4ddbd0b7 PP |
121 | |
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. | |
125 | + | |
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. | |
131 | ||
132 | ||
133 | [[ftrace-verbose]] | |
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 | |
5b1163c6 | 138 | `LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION`. |
4ddbd0b7 PP |
139 | |
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. | |
143 | + | |
144 | Fields: | |
145 | + | |
146 | [options="header"] | |
8902dadc PP |
147 | |=== |
148 | |Field name |Description | |
149 | ||
150 | |`func_addr` | |
d01f365a | 151 | |Function address. |
8902dadc PP |
152 | |
153 | |`call_site` | |
d01f365a | 154 | |Address from which this function was called. |
8902dadc | 155 | |=== |
4ddbd0b7 PP |
156 | |
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. | |
160 | + | |
161 | Fields: | |
162 | + | |
163 | [options="header"] | |
8902dadc PP |
164 | |=== |
165 | |Field name |Description | |
166 | ||
167 | |`func_addr` | |
d01f365a | 168 | |Function address. |
8902dadc PP |
169 | |
170 | |`call_site` | |
d01f365a | 171 | |Address from which this function was called. |
8902dadc | 172 | |=== |
4ddbd0b7 PP |
173 | |
174 | ||
175 | include::common-footer.txt[] | |
176 | ||
177 | include::common-copyrights.txt[] | |
178 | ||
179 | include::common-authors.txt[] | |
180 | ||
181 | ||
182 | SEE ALSO | |
183 | -------- | |
184 | man:lttng-ust(3), | |
185 | man:lttng(1), | |
186 | man:gcc(1), | |
187 | man:ld.so(8) |