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
 115 |`func_addr`
 116 |Function address
 117 |===
 118
 119 `lttng_ust_cyg_profile_fast:func_exit`::
 120     Emitted when an application function returns, or more
 121     specifically, when `__cyg_profile_func_exit()` is called.
 122 +
 123 This event has no fields. Since the `liblttng-ust-cyg-profile-fast.so`
 124 library should only be used when it can be guaranteed that the complete
 125 event stream is recorded without any missing events, a per-thread,
 126 stack-based approach can be used on the trace analyzer side to match
 127 function entry and return events.
 128
 129
 130 [[ftrace-verbose]]
 131 Verbose function tracing
 132 ~~~~~~~~~~~~~~~~~~~~~~~~
 133 The following LTTng-UST events are available when using
 134 `liblttng-ust-cyg-profile.so`. Their log level is set to
 135 `TRACE_DEBUG_FUNCTION`.
 136
 137 `lttng_ust_cyg_profile:func_entry`::
 138     Emitted when an application function is entered, or more
 139     specifically, when `__cyg_profile_func_enter()` is called.
 140 +
 141 Fields:
 142 +
 143 [options="header"]
 144 |===
 145 |Field name |Description
 146
 147 |`func_addr`
 148 |Function address
 149
 150 |`call_site`
 151 |Address from which this function was called
 152 |===
 153
 154 `lttng_ust_cyg_profile:func_exit`::
 155     Emitted when an application function returns, or more
 156     specifically, when `__cyg_profile_func_exit()` is called.
 157 +
 158 Fields:
 159 +
 160 [options="header"]
 161 |===
 162 |Field name |Description
 163
 164 |`func_addr`
 165 |Function address
 166
 167 |`call_site`
 168 |Address from which this function was called
 169 |===
 170
 171
 172 include::common-footer.txt[]
 173
 174 include::common-copyrights.txt[]
 175
 176 include::common-authors.txt[]
 177
 178
 179 SEE ALSO
 180 --------
 181 man:lttng-ust(3),
 182 man:lttng(1),
 183 man:gcc(1),
 184 man:ld.so(8)