[ltt-dev] [UST PATCH] Fix info automake and clean doc automake
Nils Carlson
nils.carlson at ericsson.com
Tue Nov 30 08:14:52 EST 2010
Fix so that info is built using automake and also clean up the
automake process so that make clean works.
Signed-off-by: Nils Carlson <nils.carlson at ericsson.com>
---
.gitignore | 1 +
configure.ac | 2 +
doc/Makefile.am | 3 +-
doc/info/Makefile.am | 2 +
doc/info/ust.texi | 634 +++++++++++++++++++++++++++++++++++++++++++++
doc/man/Makefile.am | 2 +
doc/manual/.gitignore | 1 -
doc/manual/Makefile | 4 -
doc/manual/manual.texinfo | 634 ---------------------------------------------
9 files changed, 642 insertions(+), 641 deletions(-)
create mode 100644 doc/info/Makefile.am
create mode 100644 doc/info/ust.texi
create mode 100644 doc/man/Makefile.am
delete mode 100644 doc/manual/.gitignore
delete mode 100644 doc/manual/Makefile
delete mode 100644 doc/manual/manual.texinfo
diff --git a/.gitignore b/.gitignore
index 4896a47..020c2f4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,7 @@ Makefile
*.lo
Makefile.in
*.loT
+*.info
configure
aclocal.m4
autom4te.cache/
diff --git a/configure.ac b/configure.ac
index 922e626..4fcd565 100644
--- a/configure.ac
+++ b/configure.ac
@@ -107,6 +107,8 @@ AC_MSG_RESULT($LIBFORMAT)
AC_CONFIG_FILES([
Makefile
doc/Makefile
+ doc/man/Makefile
+ doc/info/Makefile
include/Makefile
libust/Makefile
tests/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
index fa769be..37a55ac 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,2 +1 @@
-EXTRA_DIST = manual man/ustctl.1 man/ustd.1 man/usttrace.1
-man_MANS = man/ustctl.1 man/ustd.1 man/usttrace.1
+SUBDIRS = man info
\ No newline at end of file
diff --git a/doc/info/Makefile.am b/doc/info/Makefile.am
new file mode 100644
index 0000000..93d1896
--- /dev/null
+++ b/doc/info/Makefile.am
@@ -0,0 +1,2 @@
+EXTRA_DIST = ust.texi
+info_TEXINFOS = ust.texi
diff --git a/doc/info/ust.texi b/doc/info/ust.texi
new file mode 100644
index 0000000..e0565f3
--- /dev/null
+++ b/doc/info/ust.texi
@@ -0,0 +1,634 @@
+\input texinfo @c -*-texinfo-*-
+ at c %**start of header
+ at setfilename ust.info
+ at settitle LTTng Userspace Tracer (UST) Manual
+ at c %**end of header
+
+ at copying
+This manual is for program, version version.
+
+Copyright @copyright{} copyright-owner.
+
+ at quotation
+Permission is granted to ...
+ at end quotation
+ at end copying
+
+ at titlepage
+ at title LTTng Userspace Tracer (UST) Manual
+ at c @subtitle subtitle-if-any
+ at c @subtitle second-subtitle
+ at c @author author
+
+ at c The following two commands
+ at c start the copyright page.
+ at c @page
+ at c @vskip 0pt plus 1filll
+ at c @insertcopying
+
+ at c Published by ...
+ at end titlepage
+
+ at c So the toc is printed at the start.
+ at contents
+
+ at ifnottex
+ at node Top
+ at top LTTng Userspace Tracer
+
+This manual is for UST 0.5.
+ at end ifnottex
+
+ at menu
+* Overview::
+* Installation::
+* Quick start::
+* Instrumenting an application::
+* Recording a trace::
+* Viewing traces::
+* Performance::
+* Resource Usage::
+* List of environment variables detected by libust::
+* GDB integration::
+ at c * Copying:: Your rights and freedoms.
+ at end menu
+
+ at node Overview
+ at chapter Overview
+
+ at menu
+* What is UST?::
+* License::
+* Supported platforms::
+ at end menu
+
+ at node What is UST?
+ at section What is UST?
+
+The LTTng Userspace Tracer (UST) is a library accompanied by a set of tools to
+trace userspace code.
+
+Code may be instrumented with either markers or tracepoints. A highly efficient
+lockless tracer records these events to a trace buffers. These buffers are reaped
+by a deamon which writes trace data to disk.
+
+High performance is achieved by the use of lockless buffering algorithms, RCU and
+per-cpu buffers. In addition, special care is taken to minize cache impact.
+
+ at node License
+ at section License
+The LTTng Userspace Tracer is intended to be linkable to open source software
+as well as to proprietary applications. This was accomplished by licensing
+the code that needs to be linked to the traced program as @acronym{LGPL}.
+
+Components licensed as LGPL v2.1:
+ at itemize @bullet
+ at item libust
+ at item libinterfork
+ at item libustcomm
+ at end itemize
+
+Components licensed as GPL v2:
+ at itemize @bullet
+ at item ustctl
+ at item libustcmd
+ at item ustd
+ at end itemize
+
+ at node Supported platforms
+ at section Supported platforms
+
+UST can currently trace applications running on Linux, on the x86-32, x86-64
+and PowerPC 32 architectures.
+
+ at node Installation
+ at chapter Installation
+
+The LTTng userspace tracer is a library and a set of userspace tools.
+
+The following packages are required:
+
+ at itemize @bullet
+ at item
+ust
+
+This contains the tracing library, the ustd daemon, trace control tools
+and other helper tools.
+
+Repository: @url{http://git.dorsal.polymtl.ca}
+
+ at item
+liburcu
+
+This is the userspace read-copy update library by Mathieu Desnoyers.
+
+Available in Debian as package liburcu-dev.
+
+Home page: @url{http://lttng.org/urcu}
+
+ at item
+LTTV
+
+LTTV is a graphical (and text) viewer for LTTng traces.
+
+Home page: @url{http://lttng.org}
+
+ at end itemize
+
+Liburcu should be installed first. UST may then be compiled and installed. LTTV
+has no dependency on the other packages; it may therefore be installed on a
+system which does not have UST installed.
+
+Refer to the README in each of these packages for installation instructions.
+
+ at c @menu
+ at c @end menu
+
+ at node Quick start
+ at chapter Quick start
+
+First, instrument a program with a marker.
+
+ at example
+ at verbatim
+
+#include <ust/marker.h>
+
+int main(int argc, char **argv)
+{
+ int v;
+ char *st;
+
+ /* ... set values of v and st ... */
+
+ /* a marker: */
+ trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st);
+
+ /* a marker without arguments: */
+ trace_mark(ust, myotherevent, MARK_NOARGS);
+
+ return 0;
+}
+
+ at end verbatim
+ at end example
+
+Then compile it in the regular way, linking it with libust. For example:
+
+ at example
+gcc -o foo -lust foo.c
+ at end example
+
+Run the program with @command{usttrace}. The @command{usttrace} output says where the trace
+was written.
+
+ at example
+usttrace ./foo
+ at end example
+
+Finally, open the trace in LTTV.
+
+ at example
+lttv-gui -t /path/to/trace
+ at end example
+
+The trace can also be dumped as text in the console:
+
+ at example
+lttv -m textDump -t /path/to/trace
+ at end example
+
+ at node Instrumenting an application
+ at chapter Instrumenting an application
+
+In order to record a trace of events occurring in a application, the
+application must be instrumented. Instrumentation points resemble function
+calls. When the program reaches an instrumentation point, an event is
+generated.
+
+There are no limitations on the type of code that may be instrumented.
+Multi-threaded programs may be instrumented without problem. Signal handlers
+may be instrumented as well.
+
+There are two APIs to instrument programs: markers and tracepoints. Markers are
+quick to add and are usually used for temporary instrumentation. Tracepoints
+provide a way to instrument code more cleanly and are suited for permanent
+instrumentation.
+
+In addition to executable programs, shared libraries may also be instrumented
+with the methods described in this chapter.
+
+ at menu
+* Markers::
+* Tracepoints::
+ at end menu
+
+ at node Markers
+ at section Markers
+
+Adding a marker is simply a matter of inserting one line in the program.
+
+ at example
+ at verbatim
+#include <ust/marker.h>
+
+int main(int argc, char **argv)
+{
+ int v;
+ char *st;
+
+ /* ... set values of v and st ... */
+
+ /* a marker: */
+ trace_mark(main, myevent, "firstarg %d secondarg %s", v, st);
+
+ /* another marker without arguments: */
+ trace_mark(main, myotherevent, MARK_NOARGS);
+
+ return 0;
+}
+ at end verbatim
+ at end example
+
+The invocation of the trace_mark() macro requires at least 3 arguments. The
+first, here "main", is the name of the event category. It is also the name of
+the channel the event will go in. The second, here "myevent" is the name of the
+event. The third is a format string that announces the names and the types of
+the event arguments. Its format resembles that of a printf() format string; it
+is described thoroughly in Appendix x.
+
+A given Marker may appear more than once in the same program. Other Markers may
+have the same name and a different format string, although this might induce
+some confusion at analysis time.
+
+ at node Tracepoints
+ at section Tracepoints
+
+The Tracepoints API uses the Markers, but provides a higher-level abstraction.
+Whereas the markers API provides limited type checking, the Tracepoints API
+provides more thorough type checking and discharges from the need to insert
+format strings directly in the code and to have format strings appear more than
+once if a given marker is reused.
+
+ at quotation Note
+Although this example uses @emph{mychannel} as the channel, the
+only channel name currently supported with early tracing is @strong{ust}. The
+ at command{usttrace} tool always uses the early tracing mode. When using manual
+mode without early tracing, any channel name may be used.
+ at end quotation
+
+A function instrumented with a tracepoint looks like this:
+
+ at example
+ at verbatim
+#include "tp.h"
+
+void function()
+{
+ int v;
+ char *st;
+
+ /* ... set values of v and st ... */
+
+ /* a tracepoint: */
+ trace_mychannel_myevent(v, st);
+}
+ at end verbatim
+ at end example
+
+Another file, here tp.h, contains declarations for the tracepoint.
+
+ at example
+ at verbatim
+#include <ust/tracepoint.h>
+
+DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st),
+ TP_ARGS(v, st));
+ at end verbatim
+ at end example
+
+A third file, here tp.c, contains definitions for the tracepoint.
+
+ at example
+ at verbatim
+#include <ust/marker.h>
+#include "tp.h"
+
+DEFINE_TRACE(mychannel_myevent);
+
+void mychannel_myevent_probe(int v, char *st)
+{
+ trace_mark(mychannel, myevent, "v %d st %s", v, st);
+}
+
+static void __attribute__((constructor)) init()
+{
+ register_trace_mychannel_myevent(mychannel_myevent_probe);
+}
+ at end verbatim
+ at end example
+
+Here, tp.h and tp.c could contain declarations and definitions for other
+tracepoints. The constructor would contain other register_* calls.
+
+ at node Recording a trace
+ at chapter Recording a trace
+
+ at menu
+* Using @command{usttrace}::
+* Setting up the recording manually::
+* Using early tracing::
+* Crash recovery::
+* Tracing across @code{fork()} and @code{clone()}::
+* Tracing programs and libraries that were not linked to libust::
+ at end menu
+
+ at node Using @command{usttrace}
+ at section Using @command{usttrace}
+
+The simplest way to record a trace is to use the @command{usttrace} script. An
+example is given in the quickstart above.
+
+The @command{usttrace} script automatically:
+ at itemize @bullet
+ at item creates a daemon
+ at item enables all markers
+ at item runs the command specified on the command line
+ at item after the command ends, prints the location where the trace was saved
+ at end itemize
+
+Each subdirectory of the save location contains the trace of one process that
+was generated by the command. The name of a subdirectory consists in the the PID
+of the process, followed by the timestamp of its creation.
+
+The save location also contains logs of the tracing.
+
+When using @command{usttrace}, the early tracing is always active, which means
+that the tracing is guaranteed to be started by the time the process enters its
+ at code{main()} function.
+
+Several @command{usttrace}'s may be run simultaneously without risk of
+conflict. This facilitates the use of the tracer by idependent users on a
+system. Each instance of @command{usttrace} starts its own daemon which
+collects the events of the processes it creates.
+
+ at node Setting up the recording manually
+ at section Setting up the recording manually
+
+Instead of using @command{usttrace}, a trace may be recorded on an already
+running process.
+
+First the daemon must be started.
+
+ at example
+ at verbatim
+# Make sure the directory for the communication sockets exists.
+$ mkdir /tmp/ustsocks
+
+# Make sure the directory where ustd will write the trace exists.
+$ mkdir /tmp/trace
+
+# Start the daemon
+$ ustd
+
+# We assume the program we want to trace is already running and that
+# it has pid 1234.
+
+# List the available markers
+$ ustctl --list-markers 1234
+# A column indicates 0 for an inactive marker and 1 for an active marker.
+
+# Enable a marker
+$ ustctl --enable-marker ust/mymark 1234
+
+# Create a trace
+$ ustctl --create-trace 1234
+
+# Start tracing
+$ ustctl --start-trace 1234
+
+# Do things...
+
+# Stop tracing
+$ ustctl --stop-trace 1234
+
+# Destroy the trace
+$ ustctl --destroy-trace 1234
+ at end verbatim
+ at end example
+
+For more information about the manual mode, see the ustctl(1) man page.
+
+ at node Using early tracing
+ at section Using early tracing
+
+Early tracing consists in starting the tracing as early as possible in the
+program, so no events are lost between program start and the point where the
+command to start the tracing is given. When using early tracing, it is
+guaranteed that by the time the traced program enters its @code{main()}
+function, the tracing will be started.
+
+When using @command{usttrace}, the early tracing is always active.
+
+When using the manual mode (@command{ustctl}), early tracing is enabled using
+environment variables. Setting @env{UST_TRACE} to @code{1}, enables early
+tracing, while setting @env{UST_AUTOPROBE} to @code{1} enables all markers
+automatically.
+
+
+ at node Crash recovery
+ at section Crash recovery
+
+When a process being traced crashes, the daemon is able to recover all the
+events in its buffers that were successfully commited. This is possible because
+the buffers are in a shared memory segment which remains available to the
+daemon even after the termination of the traced process.
+
+ at node Tracing across @code{fork()} and @code{clone()}
+ at section Tracing across @code{fork()} and @code{clone()}
+
+Tracing across @code{clone()} when the @code{CLONE_VM} flag is specified is
+supported without any particular action.
+
+When @code{clone()} is called without @code{CLONE_VM} or @code{fork()} is
+called, a new address space is created and the tracer must be notified to
+create new buffers for it.
+
+This can be done automatically, by @env{LD_PRELOAD}'ing @file{libinterfork.so}.
+This library intercepts calls to @code{fork()} and informs the tracer it is
+being called. When using @command{usttrace}, this is accomplied by specifying
+the @option{-f} command line argument.
+
+Alternatively, the program can call @code{ust_before_fork()} before calling
+ at code{fork()} or @code{clone()} with @code{CLONE_VM}. After the call,
+ at code{ust_after_fork_parent()} must be called in the parent process and
+ at code{ust_after_fork_child()} must be called in the child process.
+
+
+ at node Tracing programs and libraries that were not linked to libust
+ at section Tracing programs and libraries that were not linked to libust
+
+Some programs need to be traced even though they were not linked to libust
+either because they were not instrumented or because it was not practical.
+
+An executable that is not instrumented can still yield interesting traces when
+at least one of its dynamic libraries is instrumented. It is also possible to
+trace certain function calls by intercepting them with a specially crafted
+library that is linked with @env{LD_PRELOAD} at program start.
+
+In any case, a program that was not linked to libust at compile time must be
+linked to it at run time with @env{LD_PRELOAD}. This can be accomplished with
+ at command{usttrace}'s @option{-l} option. It can also be done by setting the
+ at env{LD_PRELOAD} environment variable on the command line. For example:
+
+ at example
+ at verbatim
+# Run ls with usttrace, LD_PRELOAD'ing libust
+# (assuming one of the libraries used by ls is instrumented).
+$ usttrace -l ls
+
+# Run ls, manually adding the LD_PRELOAD.
+$ LD_PRELOAD=/usr/local/lib/libust.so.0 ls
+ at end verbatim
+ at end example
+
+
+ at node Performance
+ at chapter Performance
+
+Todo.
+
+ at node Viewing traces
+ at chapter Viewing traces
+
+Traces may be viewed with LTTV. An example of command for launching LTTV is
+given in the quickstart.
+
+ at menu
+* Viewing multiple traces::
+* Combined kernel-userspace tracing::
+ at end menu
+
+ at node Viewing multiple traces
+ at section Viewing multiple traces
+
+When tracing multi-process applications or several applications simultaneously,
+more than one trace will be obtained. LTTV can open and display all these
+traces simultaneously.
+
+ at node Combined kernel-userspace tracing
+ at section Combined kernel-userspace tracing
+
+In addition to multiple userspace traces, LTTV can open a kernel trace recorded
+with the LTTng kernel tracer. This provides events that enable the rendering of
+the Control Flow View and the Resource View.
+
+When doing so, it is necessary to use the same time source for the kernel
+tracer as well as the userspace tracer. Currently, the recommended method is to
+use the timestamp counter for both. The TSC can however only be used on architectures
+where it is synchronized across cores.
+
+ at node Resource Usage
+ at chapter Resource Usage
+
+The purpose of this section is to give an overview of the resource usage of libust. For
+a developer, knowing this can be important: because libust is linked with applications, it
+needs to share some resources with it. Some applications may make some assumptions that are in
+conflict with libust's usage of resources.
+
+In practice however, libust is designed to be transparent and is compatible
+with the vast majority of applications. This means no changes are required in
+the application (or library) being linked to libust.
+
+Libust is initialized by a constructor, which by definition runs before the
+ at code{main()} function of the application starts. This constructor creates a
+thread called the @emph{listener thread}. The listener thread initializes a
+named socket and waits for connections for ustd or ustctl.
+
+Libust-specific code may:
+ at itemize @bullet
+ at item use @code{malloc()} and @code{free()}
+ at item map shared memory segment in the process adress space
+ at item intercept some library calls, specifically @code{fork()} and @code{clone()}
+ at item do interprocess communication with the daemon or ustctl
+ at item create and open named sockets
+
+ at end itemize
+
+It will not:
+ at itemize @bullet
+ at item handle any signal (all signals are blocked in the listener thread)
+ at item change any process-wide setting that could confuse the application
+ at end itemize
+
+ at node List of environment variables detected by libust
+ at appendix List of environment variables detected by libust
+
+The behavior of tracing can be influenced by setting special environment
+variables in the environment of the traced application. This section
+describes these variables.
+
+ at itemize @bullet
+
+ at item
+ at env{UST_TRACE}
+
+If set to 1, start tracing as soon as the program starts. Tracing is
+guaranteed to be started by the time the @code{main()} function starts.
+
+ at item
+ at env{UST_AUTOPROBE}
+
+If set to @code{1}, enable all markers by the time the @code{main()} function starts.
+
+ at item
+ at env{UST_AUTOCOLLECT}
+
+If set to @code{0}, disable notification of daemon on trace start. Useful for
+performance tests.
+
+ at item
+ at env{UST_OVERWRITE}
+
+If set to @code{1}, enable overwriting of buffers on overrun.
+
+ at item
+ at env{UST_SUBBUF_NUM}
+
+If set, defines the default number of subbuffers per buffer.
+
+ at item
+ at env{UST_SUBBUF_SIZE}
+
+If set, defines the default size of subbuffers, in bytes.
+
+ at end itemize
+
+ at node GDB integration
+ at appendix GDB integration
+
+GDB, the GNU Debugger, can use UST markers as GDB tracepoints (note GDB has its
+own concept of tracepoint). This feature is called GDB Static Tracepoints. When
+a GDB tracepoint is hit, GDB collects the marker arguments, as well as the
+state of the registers.
+
+In UST, support for GDB integration is not compiled in by default because of
+the cost of saving registers when a marker is hit. To enable it, run the
+ at command{./configure} script with the @code{-DCONFIG_UST_GDB_INTEGRATION} flag
+in the @env{CFLAGS} environment variable. For example:
+
+ at example
+ at verbatim
+
+CFLAGS=-DCONFIG_UST_GDB_INTEGRATION ./configure
+
+ at end verbatim
+ at end example
+
+As of this writing, GDB Static Tracepoints have been submitted
+(@url{http://sourceware.org/ml/gdb-patches/2010-06/msg00592.html}) to the GDB
+mailing list.
+
+GDB integration is currently only supported on x86-32 and x86-64.
+
+ at bye
diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
new file mode 100644
index 0000000..7e18b8e
--- /dev/null
+++ b/doc/man/Makefile.am
@@ -0,0 +1,2 @@
+EXTRA_DIST = ustctl.1 ustd.1 usttrace.1
+man_MANS = ustctl.1 ustd.1 usttrace.1
diff --git a/doc/manual/.gitignore b/doc/manual/.gitignore
deleted file mode 100644
index 2460008..0000000
--- a/doc/manual/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-!Makefile
diff --git a/doc/manual/Makefile b/doc/manual/Makefile
deleted file mode 100644
index 62a430f..0000000
--- a/doc/manual/Makefile
+++ /dev/null
@@ -1,4 +0,0 @@
-all: ust.html
-
-ust.html: manual.texinfo
- makeinfo --html --no-split manual.texinfo
diff --git a/doc/manual/manual.texinfo b/doc/manual/manual.texinfo
deleted file mode 100644
index e0565f3..0000000
--- a/doc/manual/manual.texinfo
+++ /dev/null
@@ -1,634 +0,0 @@
-\input texinfo @c -*-texinfo-*-
- at c %**start of header
- at setfilename ust.info
- at settitle LTTng Userspace Tracer (UST) Manual
- at c %**end of header
-
- at copying
-This manual is for program, version version.
-
-Copyright @copyright{} copyright-owner.
-
- at quotation
-Permission is granted to ...
- at end quotation
- at end copying
-
- at titlepage
- at title LTTng Userspace Tracer (UST) Manual
- at c @subtitle subtitle-if-any
- at c @subtitle second-subtitle
- at c @author author
-
- at c The following two commands
- at c start the copyright page.
- at c @page
- at c @vskip 0pt plus 1filll
- at c @insertcopying
-
- at c Published by ...
- at end titlepage
-
- at c So the toc is printed at the start.
- at contents
-
- at ifnottex
- at node Top
- at top LTTng Userspace Tracer
-
-This manual is for UST 0.5.
- at end ifnottex
-
- at menu
-* Overview::
-* Installation::
-* Quick start::
-* Instrumenting an application::
-* Recording a trace::
-* Viewing traces::
-* Performance::
-* Resource Usage::
-* List of environment variables detected by libust::
-* GDB integration::
- at c * Copying:: Your rights and freedoms.
- at end menu
-
- at node Overview
- at chapter Overview
-
- at menu
-* What is UST?::
-* License::
-* Supported platforms::
- at end menu
-
- at node What is UST?
- at section What is UST?
-
-The LTTng Userspace Tracer (UST) is a library accompanied by a set of tools to
-trace userspace code.
-
-Code may be instrumented with either markers or tracepoints. A highly efficient
-lockless tracer records these events to a trace buffers. These buffers are reaped
-by a deamon which writes trace data to disk.
-
-High performance is achieved by the use of lockless buffering algorithms, RCU and
-per-cpu buffers. In addition, special care is taken to minize cache impact.
-
- at node License
- at section License
-The LTTng Userspace Tracer is intended to be linkable to open source software
-as well as to proprietary applications. This was accomplished by licensing
-the code that needs to be linked to the traced program as @acronym{LGPL}.
-
-Components licensed as LGPL v2.1:
- at itemize @bullet
- at item libust
- at item libinterfork
- at item libustcomm
- at end itemize
-
-Components licensed as GPL v2:
- at itemize @bullet
- at item ustctl
- at item libustcmd
- at item ustd
- at end itemize
-
- at node Supported platforms
- at section Supported platforms
-
-UST can currently trace applications running on Linux, on the x86-32, x86-64
-and PowerPC 32 architectures.
-
- at node Installation
- at chapter Installation
-
-The LTTng userspace tracer is a library and a set of userspace tools.
-
-The following packages are required:
-
- at itemize @bullet
- at item
-ust
-
-This contains the tracing library, the ustd daemon, trace control tools
-and other helper tools.
-
-Repository: @url{http://git.dorsal.polymtl.ca}
-
- at item
-liburcu
-
-This is the userspace read-copy update library by Mathieu Desnoyers.
-
-Available in Debian as package liburcu-dev.
-
-Home page: @url{http://lttng.org/urcu}
-
- at item
-LTTV
-
-LTTV is a graphical (and text) viewer for LTTng traces.
-
-Home page: @url{http://lttng.org}
-
- at end itemize
-
-Liburcu should be installed first. UST may then be compiled and installed. LTTV
-has no dependency on the other packages; it may therefore be installed on a
-system which does not have UST installed.
-
-Refer to the README in each of these packages for installation instructions.
-
- at c @menu
- at c @end menu
-
- at node Quick start
- at chapter Quick start
-
-First, instrument a program with a marker.
-
- at example
- at verbatim
-
-#include <ust/marker.h>
-
-int main(int argc, char **argv)
-{
- int v;
- char *st;
-
- /* ... set values of v and st ... */
-
- /* a marker: */
- trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st);
-
- /* a marker without arguments: */
- trace_mark(ust, myotherevent, MARK_NOARGS);
-
- return 0;
-}
-
- at end verbatim
- at end example
-
-Then compile it in the regular way, linking it with libust. For example:
-
- at example
-gcc -o foo -lust foo.c
- at end example
-
-Run the program with @command{usttrace}. The @command{usttrace} output says where the trace
-was written.
-
- at example
-usttrace ./foo
- at end example
-
-Finally, open the trace in LTTV.
-
- at example
-lttv-gui -t /path/to/trace
- at end example
-
-The trace can also be dumped as text in the console:
-
- at example
-lttv -m textDump -t /path/to/trace
- at end example
-
- at node Instrumenting an application
- at chapter Instrumenting an application
-
-In order to record a trace of events occurring in a application, the
-application must be instrumented. Instrumentation points resemble function
-calls. When the program reaches an instrumentation point, an event is
-generated.
-
-There are no limitations on the type of code that may be instrumented.
-Multi-threaded programs may be instrumented without problem. Signal handlers
-may be instrumented as well.
-
-There are two APIs to instrument programs: markers and tracepoints. Markers are
-quick to add and are usually used for temporary instrumentation. Tracepoints
-provide a way to instrument code more cleanly and are suited for permanent
-instrumentation.
-
-In addition to executable programs, shared libraries may also be instrumented
-with the methods described in this chapter.
-
- at menu
-* Markers::
-* Tracepoints::
- at end menu
-
- at node Markers
- at section Markers
-
-Adding a marker is simply a matter of inserting one line in the program.
-
- at example
- at verbatim
-#include <ust/marker.h>
-
-int main(int argc, char **argv)
-{
- int v;
- char *st;
-
- /* ... set values of v and st ... */
-
- /* a marker: */
- trace_mark(main, myevent, "firstarg %d secondarg %s", v, st);
-
- /* another marker without arguments: */
- trace_mark(main, myotherevent, MARK_NOARGS);
-
- return 0;
-}
- at end verbatim
- at end example
-
-The invocation of the trace_mark() macro requires at least 3 arguments. The
-first, here "main", is the name of the event category. It is also the name of
-the channel the event will go in. The second, here "myevent" is the name of the
-event. The third is a format string that announces the names and the types of
-the event arguments. Its format resembles that of a printf() format string; it
-is described thoroughly in Appendix x.
-
-A given Marker may appear more than once in the same program. Other Markers may
-have the same name and a different format string, although this might induce
-some confusion at analysis time.
-
- at node Tracepoints
- at section Tracepoints
-
-The Tracepoints API uses the Markers, but provides a higher-level abstraction.
-Whereas the markers API provides limited type checking, the Tracepoints API
-provides more thorough type checking and discharges from the need to insert
-format strings directly in the code and to have format strings appear more than
-once if a given marker is reused.
-
- at quotation Note
-Although this example uses @emph{mychannel} as the channel, the
-only channel name currently supported with early tracing is @strong{ust}. The
- at command{usttrace} tool always uses the early tracing mode. When using manual
-mode without early tracing, any channel name may be used.
- at end quotation
-
-A function instrumented with a tracepoint looks like this:
-
- at example
- at verbatim
-#include "tp.h"
-
-void function()
-{
- int v;
- char *st;
-
- /* ... set values of v and st ... */
-
- /* a tracepoint: */
- trace_mychannel_myevent(v, st);
-}
- at end verbatim
- at end example
-
-Another file, here tp.h, contains declarations for the tracepoint.
-
- at example
- at verbatim
-#include <ust/tracepoint.h>
-
-DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st),
- TP_ARGS(v, st));
- at end verbatim
- at end example
-
-A third file, here tp.c, contains definitions for the tracepoint.
-
- at example
- at verbatim
-#include <ust/marker.h>
-#include "tp.h"
-
-DEFINE_TRACE(mychannel_myevent);
-
-void mychannel_myevent_probe(int v, char *st)
-{
- trace_mark(mychannel, myevent, "v %d st %s", v, st);
-}
-
-static void __attribute__((constructor)) init()
-{
- register_trace_mychannel_myevent(mychannel_myevent_probe);
-}
- at end verbatim
- at end example
-
-Here, tp.h and tp.c could contain declarations and definitions for other
-tracepoints. The constructor would contain other register_* calls.
-
- at node Recording a trace
- at chapter Recording a trace
-
- at menu
-* Using @command{usttrace}::
-* Setting up the recording manually::
-* Using early tracing::
-* Crash recovery::
-* Tracing across @code{fork()} and @code{clone()}::
-* Tracing programs and libraries that were not linked to libust::
- at end menu
-
- at node Using @command{usttrace}
- at section Using @command{usttrace}
-
-The simplest way to record a trace is to use the @command{usttrace} script. An
-example is given in the quickstart above.
-
-The @command{usttrace} script automatically:
- at itemize @bullet
- at item creates a daemon
- at item enables all markers
- at item runs the command specified on the command line
- at item after the command ends, prints the location where the trace was saved
- at end itemize
-
-Each subdirectory of the save location contains the trace of one process that
-was generated by the command. The name of a subdirectory consists in the the PID
-of the process, followed by the timestamp of its creation.
-
-The save location also contains logs of the tracing.
-
-When using @command{usttrace}, the early tracing is always active, which means
-that the tracing is guaranteed to be started by the time the process enters its
- at code{main()} function.
-
-Several @command{usttrace}'s may be run simultaneously without risk of
-conflict. This facilitates the use of the tracer by idependent users on a
-system. Each instance of @command{usttrace} starts its own daemon which
-collects the events of the processes it creates.
-
- at node Setting up the recording manually
- at section Setting up the recording manually
-
-Instead of using @command{usttrace}, a trace may be recorded on an already
-running process.
-
-First the daemon must be started.
-
- at example
- at verbatim
-# Make sure the directory for the communication sockets exists.
-$ mkdir /tmp/ustsocks
-
-# Make sure the directory where ustd will write the trace exists.
-$ mkdir /tmp/trace
-
-# Start the daemon
-$ ustd
-
-# We assume the program we want to trace is already running and that
-# it has pid 1234.
-
-# List the available markers
-$ ustctl --list-markers 1234
-# A column indicates 0 for an inactive marker and 1 for an active marker.
-
-# Enable a marker
-$ ustctl --enable-marker ust/mymark 1234
-
-# Create a trace
-$ ustctl --create-trace 1234
-
-# Start tracing
-$ ustctl --start-trace 1234
-
-# Do things...
-
-# Stop tracing
-$ ustctl --stop-trace 1234
-
-# Destroy the trace
-$ ustctl --destroy-trace 1234
- at end verbatim
- at end example
-
-For more information about the manual mode, see the ustctl(1) man page.
-
- at node Using early tracing
- at section Using early tracing
-
-Early tracing consists in starting the tracing as early as possible in the
-program, so no events are lost between program start and the point where the
-command to start the tracing is given. When using early tracing, it is
-guaranteed that by the time the traced program enters its @code{main()}
-function, the tracing will be started.
-
-When using @command{usttrace}, the early tracing is always active.
-
-When using the manual mode (@command{ustctl}), early tracing is enabled using
-environment variables. Setting @env{UST_TRACE} to @code{1}, enables early
-tracing, while setting @env{UST_AUTOPROBE} to @code{1} enables all markers
-automatically.
-
-
- at node Crash recovery
- at section Crash recovery
-
-When a process being traced crashes, the daemon is able to recover all the
-events in its buffers that were successfully commited. This is possible because
-the buffers are in a shared memory segment which remains available to the
-daemon even after the termination of the traced process.
-
- at node Tracing across @code{fork()} and @code{clone()}
- at section Tracing across @code{fork()} and @code{clone()}
-
-Tracing across @code{clone()} when the @code{CLONE_VM} flag is specified is
-supported without any particular action.
-
-When @code{clone()} is called without @code{CLONE_VM} or @code{fork()} is
-called, a new address space is created and the tracer must be notified to
-create new buffers for it.
-
-This can be done automatically, by @env{LD_PRELOAD}'ing @file{libinterfork.so}.
-This library intercepts calls to @code{fork()} and informs the tracer it is
-being called. When using @command{usttrace}, this is accomplied by specifying
-the @option{-f} command line argument.
-
-Alternatively, the program can call @code{ust_before_fork()} before calling
- at code{fork()} or @code{clone()} with @code{CLONE_VM}. After the call,
- at code{ust_after_fork_parent()} must be called in the parent process and
- at code{ust_after_fork_child()} must be called in the child process.
-
-
- at node Tracing programs and libraries that were not linked to libust
- at section Tracing programs and libraries that were not linked to libust
-
-Some programs need to be traced even though they were not linked to libust
-either because they were not instrumented or because it was not practical.
-
-An executable that is not instrumented can still yield interesting traces when
-at least one of its dynamic libraries is instrumented. It is also possible to
-trace certain function calls by intercepting them with a specially crafted
-library that is linked with @env{LD_PRELOAD} at program start.
-
-In any case, a program that was not linked to libust at compile time must be
-linked to it at run time with @env{LD_PRELOAD}. This can be accomplished with
- at command{usttrace}'s @option{-l} option. It can also be done by setting the
- at env{LD_PRELOAD} environment variable on the command line. For example:
-
- at example
- at verbatim
-# Run ls with usttrace, LD_PRELOAD'ing libust
-# (assuming one of the libraries used by ls is instrumented).
-$ usttrace -l ls
-
-# Run ls, manually adding the LD_PRELOAD.
-$ LD_PRELOAD=/usr/local/lib/libust.so.0 ls
- at end verbatim
- at end example
-
-
- at node Performance
- at chapter Performance
-
-Todo.
-
- at node Viewing traces
- at chapter Viewing traces
-
-Traces may be viewed with LTTV. An example of command for launching LTTV is
-given in the quickstart.
-
- at menu
-* Viewing multiple traces::
-* Combined kernel-userspace tracing::
- at end menu
-
- at node Viewing multiple traces
- at section Viewing multiple traces
-
-When tracing multi-process applications or several applications simultaneously,
-more than one trace will be obtained. LTTV can open and display all these
-traces simultaneously.
-
- at node Combined kernel-userspace tracing
- at section Combined kernel-userspace tracing
-
-In addition to multiple userspace traces, LTTV can open a kernel trace recorded
-with the LTTng kernel tracer. This provides events that enable the rendering of
-the Control Flow View and the Resource View.
-
-When doing so, it is necessary to use the same time source for the kernel
-tracer as well as the userspace tracer. Currently, the recommended method is to
-use the timestamp counter for both. The TSC can however only be used on architectures
-where it is synchronized across cores.
-
- at node Resource Usage
- at chapter Resource Usage
-
-The purpose of this section is to give an overview of the resource usage of libust. For
-a developer, knowing this can be important: because libust is linked with applications, it
-needs to share some resources with it. Some applications may make some assumptions that are in
-conflict with libust's usage of resources.
-
-In practice however, libust is designed to be transparent and is compatible
-with the vast majority of applications. This means no changes are required in
-the application (or library) being linked to libust.
-
-Libust is initialized by a constructor, which by definition runs before the
- at code{main()} function of the application starts. This constructor creates a
-thread called the @emph{listener thread}. The listener thread initializes a
-named socket and waits for connections for ustd or ustctl.
-
-Libust-specific code may:
- at itemize @bullet
- at item use @code{malloc()} and @code{free()}
- at item map shared memory segment in the process adress space
- at item intercept some library calls, specifically @code{fork()} and @code{clone()}
- at item do interprocess communication with the daemon or ustctl
- at item create and open named sockets
-
- at end itemize
-
-It will not:
- at itemize @bullet
- at item handle any signal (all signals are blocked in the listener thread)
- at item change any process-wide setting that could confuse the application
- at end itemize
-
- at node List of environment variables detected by libust
- at appendix List of environment variables detected by libust
-
-The behavior of tracing can be influenced by setting special environment
-variables in the environment of the traced application. This section
-describes these variables.
-
- at itemize @bullet
-
- at item
- at env{UST_TRACE}
-
-If set to 1, start tracing as soon as the program starts. Tracing is
-guaranteed to be started by the time the @code{main()} function starts.
-
- at item
- at env{UST_AUTOPROBE}
-
-If set to @code{1}, enable all markers by the time the @code{main()} function starts.
-
- at item
- at env{UST_AUTOCOLLECT}
-
-If set to @code{0}, disable notification of daemon on trace start. Useful for
-performance tests.
-
- at item
- at env{UST_OVERWRITE}
-
-If set to @code{1}, enable overwriting of buffers on overrun.
-
- at item
- at env{UST_SUBBUF_NUM}
-
-If set, defines the default number of subbuffers per buffer.
-
- at item
- at env{UST_SUBBUF_SIZE}
-
-If set, defines the default size of subbuffers, in bytes.
-
- at end itemize
-
- at node GDB integration
- at appendix GDB integration
-
-GDB, the GNU Debugger, can use UST markers as GDB tracepoints (note GDB has its
-own concept of tracepoint). This feature is called GDB Static Tracepoints. When
-a GDB tracepoint is hit, GDB collects the marker arguments, as well as the
-state of the registers.
-
-In UST, support for GDB integration is not compiled in by default because of
-the cost of saving registers when a marker is hit. To enable it, run the
- at command{./configure} script with the @code{-DCONFIG_UST_GDB_INTEGRATION} flag
-in the @env{CFLAGS} environment variable. For example:
-
- at example
- at verbatim
-
-CFLAGS=-DCONFIG_UST_GDB_INTEGRATION ./configure
-
- at end verbatim
- at end example
-
-As of this writing, GDB Static Tracepoints have been submitted
-(@url{http://sourceware.org/ml/gdb-patches/2010-06/msg00592.html}) to the GDB
-mailing list.
-
-GDB integration is currently only supported on x86-32 and x86-64.
-
- at bye
--
1.7.1
More information about the lttng-dev
mailing list