contents/using-lttng/instrumenting/prebuilt-ust-helpers/liblttng-ust-cyg-profile.md

   1 ---
   2 id: liblttng-ust-cyg-profile
   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
  31 <div class="table">
  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>&nbsp;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>
  69 </div>
  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
  86 <div class="table">
  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>&nbsp;address of the
 109                         called function
 110                     </li>
 111                     <li>
 112                         <code class="arg">call_site</code>&nbsp;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>&nbsp;address of the
 128                         called function
 129                     </li>
 130                     <li>
 131                         <code class="arg">call_site</code>&nbsp;call site
 132                         address
 133                     </li>
 134                 </ul>
 135             </td>
 136         </tr>
 137     </tbody>
 138 </table>
 139 </div>
 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)).