NAME¶
lttng-ust-cyg-profile — LTTng UST 2.x Function Tracing
SYNOPSIS¶
Compile the application source code with option
-finstrument-functions
and launch your application either with:
- LD_PRELOAD=liblttng-ust-cyg-profile-fast.so appname
or (to use verbose function tracing)
- LD_PRELOAD=liblttng-ust-cyg-profile.so appname
All events emitted for function tracing are provided on loglevel
TRACE_DEBUG_FUNCTION. The following command can be used to add function
tracing events in your trace session:
- lttng enable-event -u -a --loglevel-only TRACE_DEBUG_FUNCTION
DESCRIPTION¶
For compilers that provide code generation option
-finstrument-functions
(e.g. GCC and LLVM/Clang) LTTng-UST provides shared libraries that allow users
to trace the function flow of their applications.
Function tracing comes in two flavors (each providing different trade-offs):
- 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 recored as
lttng_ust_cyg_profile_fast:func_entry. Function exit is recorded as
lttng_ust_cyg_profile_fast:func_exit (without any field data).
- 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.
For each function entry and exit the address of the called function and the
call site address are recorded as lttng_ust_cyg_profile:func_entry and
lttng_ust_cyg_profile:func_exit.
USAGE¶
To use function tracing you need to make sure the sources of your application
are compiled with -finstrument-functions. 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 during run time. Usually there are additional
compiler flags that allow you to specify more fine grained selection of
function instrumentation.
For each instrumented function the executable will contain calls to profiling
function hooks (after function entry and just before function exit).
By preloading (LD_PRELOAD) one of the provided shared libraries, these profiling
hooks get defined to emit LTTng events (as described above).
Using this feature can result in massive amount trace data to be generated by
the instrumented application. Application runtime is also considerably
affected. Be careful on systems with limited resources.
SEE ALSO¶
lttng-ust(3),
lttng(1),
gcc(1),
ld.so(8)
BUGS¶
If you encounter any issues or usability problem, please report it on our
mailing list <lttng-dev@lists.lttng.org> to help improve this project.
CREDITS¶
liblttng-ust is distributed under the GNU Lesser General Public License version
2.1. The headers are distributed under the MIT license.
See
http://lttng.org for more information on the LTTng project.
Mailing list for support and development: <lttng-dev@lists.lttng.org>.
You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
AUTHORS¶
liblttng-ust was originally written by Mathieu Desnoyers, with additional
contributions from various other people. It is currently maintained by Mathieu
Desnoyers <mathieu.desnoyers@efficios.com>.