Commit | Line | Data |
---|---|---|
5e0cbfb0 | 1 | --- |
cb987a4a | 2 | id: liblttng-ust-cyg-profile |
5e0cbfb0 PP |
3 | --- |
4 | ||
5 | Function tracing is the recording of which functions are entered and | |
6 | left during the execution of an application. Like with any LTTng event, | |
7 | the precise time at which this happens is also kept. | |
8 | ||
9 | GCC and clang have an option named | |
10 | <a href="https://gcc.gnu.org/onlinedocs/gcc-4.9.1/gcc/Code-Gen-Options.html" class="ext"><code>-finstrument-functions</code></a> | |
11 | which generates instrumentation calls for entry and exit to functions. | |
12 | The LTTng-UST function tracing helpers, `liblttng-ust-cyg-profile.so` | |
13 | and `liblttng-ust-cyg-profile-fast.so`, take advantage of this feature | |
14 | to add instrumentation to the two generated functions (which contain | |
15 | `cyg_profile` in their names, hence the shared object's name). | |
16 | ||
17 | In order to use LTTng-UST function tracing, the translation units to | |
18 | instrument must be built using the `-finstrument-functions` compiler | |
19 | flag. | |
20 | ||
21 | LTTng-UST function tracing comes in two flavors, each providing | |
22 | different trade-offs: `liblttng-ust-cyg-profile-fast.so` and | |
23 | `liblttng-ust-cyg-profile.so`. | |
24 | ||
25 | **`liblttng-ust-cyg-profile-fast.so`** is a lightweight variant that | |
26 | should only be used where it can be _guaranteed_ that the complete event | |
27 | stream is recorded without any missing events. Any kind of duplicate | |
28 | information is left out. This version registers the following | |
29 | tracepoints: | |
30 | ||
f6875860 | 31 | <div class="table"> |
5e0cbfb0 PP |
32 | <table class="func-desc"> |
33 | <thead> | |
34 | <tr> | |
35 | <th><abbr title="Tracepoint">TP</abbr> provider name</th> | |
36 | <th><abbr title="Tracepoint">TP</abbr> name</th> | |
37 | <th>Description/fields</th> | |
38 | </tr> | |
39 | </thead> | |
40 | <tbody> | |
41 | <tr> | |
42 | <td rowspan="2"> | |
43 | <code class="no-bg">lttng_ust_cyg_profile_fast</code> | |
44 | </td> | |
45 | <td> | |
46 | <code class="no-bg">func_entry</code> | |
47 | </td> | |
48 | <td> | |
49 | <p>Function entry</p> | |
50 | ||
51 | <ul> | |
52 | <li> | |
53 | <code class="arg">addr</code> address of the | |
54 | called function | |
55 | </li> | |
56 | </ul> | |
57 | </td> | |
58 | </tr> | |
59 | <tr> | |
60 | <td> | |
61 | <code class="no-bg">func_exit</code> | |
62 | </td> | |
63 | <td> | |
64 | <p>Function exit</p> | |
65 | </td> | |
66 | </tr> | |
67 | </tbody> | |
68 | </table> | |
f6875860 | 69 | </div> |
5e0cbfb0 PP |
70 | |
71 | Assuming no event is lost, having only the function addresses on entry | |
72 | is enough for creating a call graph (remember that a recorded event | |
73 | always contains the ID of the CPU that generated it). A tool like | |
74 | <a href="https://sourceware.org/binutils/docs/binutils/addr2line.html" class="ext"><code>addr2line</code></a> | |
75 | may be used to convert function addresses back to source files names | |
76 | and line numbers. | |
77 | ||
78 | The other helper, | |
79 | **`liblttng-ust-cyg-profile.so`**, | |
80 | is a more robust variant which also works for use cases where | |
81 | events might get discarded or not recorded from application startup. | |
82 | In these cases, the trace analyzer needs extra information to be | |
83 | able to reconstruct the program flow. This version registers the | |
84 | following tracepoints: | |
85 | ||
f6875860 | 86 | <div class="table"> |
5e0cbfb0 PP |
87 | <table class="func-desc"> |
88 | <thead> | |
89 | <tr> | |
90 | <th><abbr title="Tracepoint">TP</abbr> provider name</th> | |
91 | <th><abbr title="Tracepoint">TP</abbr> name</th> | |
92 | <th>Description/fields</th> | |
93 | </tr> | |
94 | </thead> | |
95 | <tbody> | |
96 | <tr> | |
97 | <td rowspan="2"> | |
98 | <code class="no-bg">lttng_ust_cyg_profile</code> | |
99 | </td> | |
100 | <td> | |
101 | <code class="no-bg">func_entry</code> | |
102 | </td> | |
103 | <td> | |
104 | <p>Function entry</p> | |
105 | ||
106 | <ul> | |
107 | <li> | |
108 | <code class="arg">addr</code> address of the | |
109 | called function | |
110 | </li> | |
111 | <li> | |
112 | <code class="arg">call_site</code> call site | |
113 | address | |
114 | </li> | |
115 | </ul> | |
116 | </td> | |
117 | </tr> | |
118 | <tr> | |
119 | <td> | |
120 | <code class="no-bg">func_exit</code> | |
121 | </td> | |
122 | <td> | |
123 | <p>Function exit</p> | |
124 | ||
125 | <ul> | |
126 | <li> | |
127 | <code class="arg">addr</code> address of the | |
128 | called function | |
129 | </li> | |
130 | <li> | |
131 | <code class="arg">call_site</code> call site | |
132 | address | |
133 | </li> | |
134 | </ul> | |
135 | </td> | |
136 | </tr> | |
137 | </tbody> | |
138 | </table> | |
f6875860 | 139 | </div> |
5e0cbfb0 PP |
140 | |
141 | To use one or the other variant with any user application, assuming at | |
142 | least one translation unit of the latter is compiled with the | |
143 | `-finstrument-functions` option, do: | |
144 | ||
145 | <pre class="term"> | |
146 | LD_PRELOAD=liblttng-ust-cyg-profile-fast.so my-app | |
147 | </pre> | |
148 | ||
149 | or | |
150 | ||
151 | <pre class="term"> | |
152 | LD_PRELOAD=liblttng-ust-cyg-profile.so my-app | |
153 | </pre> | |
154 | ||
155 | It might be necessary to limit the number of source files where | |
156 | `-finstrument-functions` is used to prevent excessive amount of trace | |
157 | data to be generated at runtime. | |
158 | ||
159 | <div class="tip"> | |
160 | <p> | |
161 | <span class="t">Tip:</span> When using GCC, at least, you may use | |
162 | the | |
163 | <code>-finstrument-functions-exclude-function-list</code> | |
164 | option to avoid instrumenting entries and exits of specific | |
165 | symbol names. | |
166 | </p> | |
167 | </div> | |
168 | ||
169 | All events generated from LTTng-UST function tracing are provided on | |
170 | log level `TRACE_DEBUG_FUNCTION`, which is useful to easily enable | |
171 | function tracing events in your tracing session using the | |
172 | `--loglevel-only` option of `lttng enable-event` | |
173 | (see [Controlling tracing](#doc-controlling-tracing)). |