--- /dev/null
+lttng-ust-dl(3)
+===============
+:object-type: library
+
+
+NAME
+----
+lttng-ust-cyg-profile - Function tracing (LTTng-UST helper)
+
+
+SYNOPSIS
+--------
+Compile your application with compiler option
+nloption:-finstrument-functions.
+
+Launch your application by preloading
+`liblttng-ust-cyg-profile-fast.so` for fast function tracing:
+
+[role="term"]
+[verse]
+*LD_PRELOAD=liblttng-ust-cyg-profile-fast.so* my-app
+
+Launch your application by preloading
+`liblttng-ust-cyg-profile.so` for slower, more verbose function
+tracing:
+
+[role="term"]
+[verse]
+*LD_PRELOAD=liblttng-ust-cyg-profile.so* my-app
+
+
+DESCRIPTION
+-----------
+When the `liblttng-ust-cyg-profile.so` or the
+`liblttng-ust-cyg-profile-fast.so` library is preloaded before a given
+application starts, all function entry and return points are traced by
+LTTng-UST (see man:lttng-ust(3)), provided said application was compiled
+with the nloption:-finstrument-functions compiler option.
+
+See man:lttng(1) to learn more about how to control LTTng tracing
+sessions.
+
+Function tracing with LTTng-UST comes in two flavors, each one
+providing a different trade-off between performance and robustness:
+
+`liblttng-ust-cyg-profile-fast.so`::
+ This is a lightweight variant that should only be used where it can
+ be _guaranteed_ that the complete event stream is recorded without
+ any missing events. Any kind of duplicate information is left out.
++
+At each function entry, the address of the called function is
+recorded in an LTTng-UST event. Function exits are recorded as
+another, empty LTTng-UST event.
++
+See the <<ftrace-fast,Fast function tracing>> section below for the
+complete list of emitted events and their fields.
+
+`liblttng-ust-cyg-profile.so`::
+ This is a more robust variant which also works for use cases where
+ events might get discarded, or not recorded from application
+ startup. In these cases, the trace analyzer needs extra
+ information to be able to reconstruct the program flow.
++
+At each function entry _and_ exit, the address of the called
+function _and_ the call site address are recorded in an LTTng-UST
+event.
++
+See the <<ftrace-verbose,Verbose function tracing>> section below for
+the complete list of emitted events and their fields.
+
+
+Usage
+~~~~~
+To use LTTng-UST function tracing, you need to make sure the sources of
+your application are compiled with the nloption:-finstrument-functions
+compiler option.
+
+It might be necessary to limit the number of source files where this
+option is used to prevent excessive amount of trace data to be generated
+at run time. Usually, there are additional compiler flags that allow
+you to specify a more fine-grained selection of function
+instrumentation.
+
+For each instrumented function, the executable will contain calls to
+profiling function hooks (after function entry, named `__cyg_profile_func_enter()`,
+and just before function exit, named `__cyg_profile_func_exit()`).
+
+By preloading (using the `LD_PRELOAD` environment variable) one of the
+provided shared libraries, these profiling hooks get defined to emit
+LTTng events (as described below).
+
+NOTE: Using this feature can result in a *massive amount* of trace data
+to be generated by the instrumented application. Application run time is
+also considerably affected. Be careful on systems with limited
+resources.
+
+
+[[ftrace-fast]]
+Fast function tracing
+~~~~~~~~~~~~~~~~~~~~~
+The following LTTng-UST events are available when using
+`liblttng-ust-cyg-profile-fast.so`. Their log level is set to
+`TRACE_DEBUG_FUNCTION`.
+
+`lttng_ust_cyg_profile_fast:func_entry`::
+ Emitted when an application function is entered, or more
+ specifically, when `__cyg_profile_func_enter()` is called.
++
+Fields:
++
+[options="header"]
+|=========================================================================
+| Field name | Description
+| `func_addr` | Function address
+|=========================================================================
+
+`lttng_ust_cyg_profile_fast:func_exit`::
+ Emitted when an application function returns, or more
+ specifically, when `__cyg_profile_func_exit()` is called.
++
+This event has no fields. Since the `liblttng-ust-cyg-profile-fast.so`
+library should only be used when it can be guaranteed that the complete
+event stream is recorded without any missing events, a per-thread,
+stack-based approach can be used on the trace analyzer side to match
+function entry and return events.
+
+
+[[ftrace-verbose]]
+Verbose function tracing
+~~~~~~~~~~~~~~~~~~~~~~~~
+The following LTTng-UST events are available when using
+`liblttng-ust-cyg-profile.so`. Their log level is set to
+`TRACE_DEBUG_FUNCTION`.
+
+`lttng_ust_cyg_profile:func_entry`::
+ Emitted when an application function is entered, or more
+ specifically, when `__cyg_profile_func_enter()` is called.
++
+Fields:
++
+[options="header"]
+|=========================================================================
+| Field name | Description
+| `func_addr` | Function address
+| `call_site` | Address from which this function was called
+|=========================================================================
+
+`lttng_ust_cyg_profile:func_exit`::
+ Emitted when an application function returns, or more
+ specifically, when `__cyg_profile_func_exit()` is called.
++
+Fields:
++
+[options="header"]
+|=========================================================================
+| Field name | Description
+| `func_addr` | Function address
+| `call_site` | Address from which this function was called
+|=========================================================================
+
+
+include::common-footer.txt[]
+
+include::common-copyrights.txt[]
+
+include::common-authors.txt[]
+
+
+SEE ALSO
+--------
+man:lttng-ust(3),
+man:lttng(1),
+man:gcc(1),
+man:ld.so(8)
projects / lttng-ust.git / blobdiff