doc/man/lttng-ust-cyg-profile.3.txt

   1 lttng-ust-dl(3)
   2 ===============
   3 :object-type: library
   4
   5
   6 NAME
   7 ----
   8 lttng-ust-cyg-profile - Function tracing (LTTng-UST helper)
   9
  10
  11 SYNOPSIS
  12 --------
  13 Compile your application with compiler option
  14 nloption:-finstrument-functions.
  15
  16 Launch your application by preloading
  17 `liblttng-ust-cyg-profile-fast.so` for fast function tracing:
  18
  19 [role="term"]
  20 [verse]
  21 *LD_PRELOAD=liblttng-ust-cyg-profile-fast.so* my-app
  22
  23 Launch your application by preloading
  24 `liblttng-ust-cyg-profile.so` for slower, more verbose function
  25 tracing:
  26
  27 [role="term"]
  28 [verse]
  29 *LD_PRELOAD=liblttng-ust-cyg-profile.so* my-app
  30
  31
  32 DESCRIPTION
  33 -----------
  34 When the `liblttng-ust-cyg-profile.so` or the
  35 `liblttng-ust-cyg-profile-fast.so` library is preloaded before a given
  36 application starts, all function entry and return points are traced by
  37 LTTng-UST (see man:lttng-ust(3)), provided said application was compiled
  38 with the nloption:-finstrument-functions compiler option.
  39
  40 See man:lttng(1) to learn more about how to control LTTng tracing
  41 sessions.
  42
  43 Function tracing with LTTng-UST comes in two flavors, each one
  44 providing a different trade-off between performance and robustness:
  45
  46 `liblttng-ust-cyg-profile-fast.so`::
  47     This is a lightweight variant that should only be used where it can
  48     be _guaranteed_ that the complete event stream is recorded without
  49     any missing events. Any kind of duplicate information is left out.
  50 +
  51 At each function entry, the address of the called function is
  52 recorded in an LTTng-UST event. Function exits are recorded as
  53 another, empty LTTng-UST event.
  54 +
  55 See the <<ftrace-fast,Fast function tracing>> section below for the
  56 complete list of emitted events and their fields.
  57
  58 `liblttng-ust-cyg-profile.so`::
  59       This is a more robust variant which also works for use cases where
  60       events might get discarded, or not recorded from application
  61       startup. In these cases, the trace analyzer needs extra
  62       information to be able to reconstruct the program flow.
  63 +
  64 At each function entry _and_ exit, the address of the called
  65 function _and_ the call site address are recorded in an LTTng-UST
  66 event.
  67 +
  68 See the <<ftrace-verbose,Verbose function tracing>> section below for
  69 the complete list of emitted events and their fields.
  70
  71
  72 Usage
  73 ~~~~~
  74 To use LTTng-UST function tracing, you need to make sure the sources of
  75 your application are compiled with the nloption:-finstrument-functions
  76 compiler option.
  77
  78 It might be necessary to limit the number of source files where this
  79 option is used to prevent excessive amount of trace data to be generated
  80 at run time. Usually, there are additional compiler flags that allow
  81 you to specify a more fine-grained selection of function
  82 instrumentation.
  83
  84 For each instrumented function, the executable will contain calls to
  85 profiling function hooks (after function entry, named `__cyg_profile_func_enter()`,
  86 and just before function exit, named `__cyg_profile_func_exit()`).
  87
  88 By preloading (using the `LD_PRELOAD` environment variable) one of the
  89 provided shared libraries, these profiling hooks get defined to emit
  90 LTTng events (as described below).
  91
  92 NOTE: Using this feature can result in a *massive amount* of trace data
  93 to be generated by the instrumented application. Application run time is
  94 also considerably affected. Be careful on systems with limited
  95 resources.
  96
  97
  98 [[ftrace-fast]]
  99 Fast function tracing
 100 ~~~~~~~~~~~~~~~~~~~~~
 101 The following LTTng-UST events are available when using
 102 `liblttng-ust-cyg-profile-fast.so`. Their log level is set to
 103 `TRACE_DEBUG_FUNCTION`.
 104
 105 `lttng_ust_cyg_profile_fast:func_entry`::
 106     Emitted when an application function is entered, or more
 107     specifically, when `__cyg_profile_func_enter()` is called.
 108 +
 109 Fields:
 110 +
 111 [options="header"]
 112 |=========================================================================
 113 | Field name                 | Description
 114 | `func_addr`                | Function address
 115 |=========================================================================
 116
 117 `lttng_ust_cyg_profile_fast:func_exit`::
 118     Emitted when an application function returns, or more
 119     specifically, when `__cyg_profile_func_exit()` is called.
 120 +
 121 This event has no fields. Since the `liblttng-ust-cyg-profile-fast.so`
 122 library should only be used when it can be guaranteed that the complete
 123 event stream is recorded without any missing events, a per-thread,
 124 stack-based approach can be used on the trace analyzer side to match
 125 function entry and return events.
 126
 127
 128 [[ftrace-verbose]]
 129 Verbose function tracing
 130 ~~~~~~~~~~~~~~~~~~~~~~~~
 131 The following LTTng-UST events are available when using
 132 `liblttng-ust-cyg-profile.so`. Their log level is set to
 133 `TRACE_DEBUG_FUNCTION`.
 134
 135 `lttng_ust_cyg_profile:func_entry`::
 136     Emitted when an application function is entered, or more
 137     specifically, when `__cyg_profile_func_enter()` is called.
 138 +
 139 Fields:
 140 +
 141 [options="header"]
 142 |=========================================================================
 143 | Field name                 | Description
 144 | `func_addr`                | Function address
 145 | `call_site`                | Address from which this function was called
 146 |=========================================================================
 147
 148 `lttng_ust_cyg_profile:func_exit`::
 149     Emitted when an application function returns, or more
 150     specifically, when `__cyg_profile_func_exit()` is called.
 151 +
 152 Fields:
 153 +
 154 [options="header"]
 155 |=========================================================================
 156 | Field name                 | Description
 157 | `func_addr`                | Function address
 158 | `call_site`                | Address from which this function was called
 159 |=========================================================================
 160
 161
 162 include::common-footer.txt[]
 163
 164 include::common-copyrights.txt[]
 165
 166 include::common-authors.txt[]
 167
 168
 169 SEE ALSO
 170 --------
 171 man:lttng-ust(3),
 172 man:lttng(1),
 173 man:gcc(1),
 174 man:ld.so(8)