From d1eaa4d7ea9c1e1c6ec56cc10a29aa67f25ced19 Mon Sep 17 00:00:00 2001 From: Paul Woegerer Date: Wed, 27 Mar 2013 12:24:34 -0400 Subject: [PATCH] Add man page for lttng-ust-cyg-profile [ Edit by Mathieu Desnoyers: minor edits, add reference from lttng-ust(3) to lttng-ust-cyg-profile(3). ] Signed-off-by: Mathieu Desnoyers --- doc/Makefile.am | 3 +- doc/man/lttng-ust-cyg-profile.3 | 79 +++++++++++++++++++++++++++++++++ doc/man/lttng-ust.3 | 3 +- 3 files changed, 83 insertions(+), 2 deletions(-) create mode 100644 doc/man/lttng-ust-cyg-profile.3 diff --git a/doc/Makefile.am b/doc/Makefile.am index 66c22fa8..ccd6d189 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,5 @@ SUBDIRS = . examples dist_man_MANS = man/lttng-gen-tp.1 \ - man/lttng-ust.3 + man/lttng-ust.3 \ + man/lttng-ust-cyg-profile.3 diff --git a/doc/man/lttng-ust-cyg-profile.3 b/doc/man/lttng-ust-cyg-profile.3 new file mode 100644 index 00000000..2fe421ad --- /dev/null +++ b/doc/man/lttng-ust-cyg-profile.3 @@ -0,0 +1,79 @@ +.TH "LTTNG-UST-CYG-PROFILE" "3" "March 26, 2013" "" "" +.SH "NAME" +lttng-ust-cyg-profile \(em LTTng UST Function Tracing +.SH "SYNOPSIS" +Compile the application source code with option \fB-finstrument-functions\fP +and launch your application either with: +.TP +\fBLD_PRELOAD=liblttng-ust-cyg-profile-fast.so\fP appname +.PP +or (to use verbose function tracing) +.TP +\fBLD_PRELOAD=liblttng-ust-cyg-profile.so\fP appname +.PP +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: +.TP +.B lttng enable-event -u -a --loglevel-only TRACE_DEBUG_FUNCTION +.SH "DESCRIPTION" +For compilers that provide code generation option +\fB-finstrument-functions\fP (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): +.IP 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). + +.IP 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. +.SH "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. +.SH "SEE ALSO" +lttng-ust(3), lttng(1), gcc(1), ld.so(8) +.SH "BUGS" +If you encounter any issues or usability problem, please report it on +our mailing list to help improve this +project. +.SH "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: . + +You can find us on IRC server irc.oftc.net (OFTC) in #lttng. +.SH "AUTHORS" +liblttng-ust was originally written by Mathieu Desnoyers, with additional +contributions from various other people. It is currently maintained by +Mathieu Desnoyers . diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 7cc3bfde..228d2f89 100644 --- a/doc/man/lttng-ust.3 +++ b/doc/man/lttng-ust.3 @@ -360,7 +360,8 @@ startup time. .SH "SEE ALSO" .PP -lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-sessiond(8) +lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3), +lttng-sessiond(8) .PP .SH "BUGS" -- 2.34.1