doc/man: document LTTng-UST 2.13

[lttng-ust.git] / doc / man / lttng-ust-cyg-profile.3.txt

lttng-ust-cyg-profile(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
`LTTNG_UST_TRACEPOINT_LOGLEVEL_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
`LTTNG_UST_TRACEPOINT_LOGLEVEL_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)