[lttng-dev] [lttng-ust PATCH] Add man page for lttng-ust-cyg-profile

Woegerer, Paul Paul_Woegerer at mentor.com
Wed Mar 27 12:14:56 EDT 2013


As promised...

>From acba8cd14abc7e61cf1346b5649972bac3ea0d53 Mon Sep 17 00:00:00 2001
From: Paul Woegerer <paul_woegerer at mentor.com>
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 <lttng-dev at lists.lttng.org> 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: <lttng-dev at lists.lttng.org>.
+
+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 <mathieu.desnoyers at efficios.com>.
-- 
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.



More information about the lttng-dev mailing list