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 <table class="func-desc">
  32     <thead>
  33         <tr>
  34             <th><abbr title="Tracepoint">TP</abbr> provider name</th>
  35             <th><abbr title="Tracepoint">TP</abbr> name</th>
  36             <th>Description/fields</th>
  37         </tr>
  38     </thead>
  39     <tbody>
  40         <tr>
  41             <td rowspan="2">
  42                 <code class="no-bg">lttng_ust_cyg_profile_fast</code>
  43             </td>
  44             <td>
  45                 <code class="no-bg">func_entry</code>
  46             </td>
  47             <td>
  48                 <p>Function entry</p>
  49
  50                 <ul>
  51                     <li>
  52                         <code class="arg">addr</code>&nbsp;address of the
  53                         called function
  54                     </li>
  55                 </ul>
  56             </td>
  57         </tr>
  58         <tr>
  59             <td>
  60                 <code class="no-bg">func_exit</code>
  61             </td>
  62             <td>
  63                 <p>Function exit</p>
  64             </td>
  65         </tr>
  66     </tbody>
  67 </table>
  68
  69 Assuming no event is lost, having only the function addresses on entry
  70 is enough for creating a call graph (remember that a recorded event
  71 always contains the ID of the CPU that generated it). A tool like
  72 <a href="https://sourceware.org/binutils/docs/binutils/addr2line.html" class="ext"><code>addr2line</code></a>
  73 may be used to convert function addresses back to source files names
  74 and line numbers.
  75
  76 The other helper,
  77 **`liblttng-ust-cyg-profile.so`**,
  78 is a more robust variant which also works for use cases where
  79 events might get discarded or not recorded from application startup.
  80 In these cases, the trace analyzer needs extra information to be
  81 able to reconstruct the program flow. This version registers the
  82 following tracepoints:
  83
  84 <table class="func-desc">
  85     <thead>
  86         <tr>
  87             <th><abbr title="Tracepoint">TP</abbr> provider name</th>
  88             <th><abbr title="Tracepoint">TP</abbr> name</th>
  89             <th>Description/fields</th>
  90         </tr>
  91     </thead>
  92     <tbody>
  93         <tr>
  94             <td rowspan="2">
  95                 <code class="no-bg">lttng_ust_cyg_profile</code>
  96             </td>
  97             <td>
  98                 <code class="no-bg">func_entry</code>
  99             </td>
 100             <td>
 101                 <p>Function entry</p>
 102
 103                 <ul>
 104                     <li>
 105                         <code class="arg">addr</code>&nbsp;address of the
 106                         called function
 107                     </li>
 108                     <li>
 109                         <code class="arg">call_site</code>&nbsp;call site
 110                         address
 111                     </li>
 112                 </ul>
 113             </td>
 114         </tr>
 115         <tr>
 116             <td>
 117                 <code class="no-bg">func_exit</code>
 118             </td>
 119             <td>
 120                 <p>Function exit</p>
 121
 122                 <ul>
 123                     <li>
 124                         <code class="arg">addr</code>&nbsp;address of the
 125                         called function
 126                     </li>
 127                     <li>
 128                         <code class="arg">call_site</code>&nbsp;call site
 129                         address
 130                     </li>
 131                 </ul>
 132             </td>
 133         </tr>
 134     </tbody>
 135 </table>
 136
 137 To use one or the other variant with any user application, assuming at
 138 least one translation unit of the latter is compiled with the
 139 `-finstrument-functions` option, do:
 140
 141 <pre class="term">
 142 LD_PRELOAD=liblttng-ust-cyg-profile-fast.so my-app
 143 </pre>
 144
 145 or
 146
 147 <pre class="term">
 148 LD_PRELOAD=liblttng-ust-cyg-profile.so my-app
 149 </pre>
 150
 151 It might be necessary to limit the number of source files where
 152 `-finstrument-functions` is used to prevent excessive amount of trace
 153 data to be generated at runtime.
 154
 155 <div class="tip">
 156 <p>
 157     <span class="t">Tip:</span> When using GCC, at least, you may use
 158     the
 159     <code>-finstrument-functions-exclude-function-list</code>
 160     option to avoid instrumenting entries and exits of specific
 161     symbol names.
 162 </p>
 163 </div>
 164
 165 All events generated from LTTng-UST function tracing are provided on
 166 log level `TRACE_DEBUG_FUNCTION`, which is useful to easily enable
 167 function tracing events in your tracing session using the
 168 `--loglevel-only` option of `lttng enable-event`
 169 (see [Controlling tracing](#doc-controlling-tracing)).