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

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