* Woegerer, Paul ([email protected]) wrote: > As promised... merged, with minor edits, thanks!
Mathieu > > From acba8cd14abc7e61cf1346b5649972bac3ea0d53 Mon Sep 17 00:00:00 2001 > From: Paul Woegerer <[email protected]> > Date: Wed, 27 Mar 2013 17:02:27 +0100 > Subject: [PATCH] Add man page for lttng-ust-cyg-profile > > --- > doc/Makefile.am | 3 +- > doc/man/lttng-ust-cyg-profile.3 | 79 > +++++++++++++++++++++++++++++++++++++++ > 2 files changed, 81 insertions(+), 1 deletion(-) > create mode 100644 doc/man/lttng-ust-cyg-profile.3 > > diff --git a/doc/Makefile.am b/doc/Makefile.am > index 66c22fa..ccd6d18 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 0000000..58dbce8 > --- /dev/null > +++ b/doc/man/lttng-ust-cyg-profile.3 > @@ -0,0 +1,79 @@ > +.TH "LTTNG-UST-CYG-PROFILE" "1" "March 26, 2013" "" "" > +.SH "NAME" > +lttng-ust-cyg-profile \(em LTTng UST 2.0 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 <[email protected]> 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: <[email protected]>. > + > +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 <[email protected]>. > -- > 1.7.10.4 > > > -- > Paul Woegerer | SW Development Engineer > http://go.mentor.com/sourceryanalyzer > > Mentor Embedded(tm) | Prinz Eugen Straße 72/2/4, Vienna, 1040 Austria > Nucleus® | Linux® | Android(tm) | Services | UI | Multi-OS > > Android is a trademark of Google Inc. Use of this trademark is subject to > Google Permissions. > Linux is the registered trademark of Linus Torvalds in the U.S. and other > countries. -- Mathieu Desnoyers EfficiOS Inc. http://www.efficios.com _______________________________________________ lttng-dev mailing list [email protected] http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
