[ltt-dev] [UST PATCH] Fix info automake and clean doc automake
Mathieu Desnoyers
compudj at krystal.dyndns.org
Tue Nov 30 10:10:52 EST 2010
* Nils Carlson (nils.carlson at ericsson.com) wrote:
> Fix so that info is built using automake and also clean up the
> automake process so that make clean works.
This makes sense! Thanks,
Acked-by: Mathieu Desnoyers <mathieu.desnoyers at efficios.com>
>
> 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
>
>
> _______________________________________________
> ltt-dev mailing list
> ltt-dev at lists.casi.polymtl.ca
> http://lists.casi.polymtl.ca/cgi-bin/mailman/listinfo/ltt-dev
>
--
Mathieu Desnoyers
Operating System Efficiency R&D Consultant
EfficiOS Inc.
http://www.efficios.com
More information about the lttng-dev
mailing list