@node Top
@top LTTng Userspace Tracer
-This manual is for UST 0.1.
+This manual is for UST 0.5.
@end ifnottex
@menu
* Recording a trace::
* Viewing traces::
* Performance::
+* Resource Usage::
+* List of environment variables detected by libust::
+* GDB integration::
@c * Copying:: Your rights and freedoms.
@end menu
@chapter Overview
@menu
+* What is UST?::
* License::
* Supported platforms::
@end menu
+@node What is UST?
+@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.
+
@node License
@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}.
-The @file{libust} library, including its headers, are licensed as @acronym{GNU}
-@acronym{LGPL} v2.1. It is also the case of some other helper libraries
-(@file{libmallocwrap}, @file{libinterfork}, @file{libustcomm}) that need to be linked to the traced
-program.
+Components licensed as LGPL v2.1:
+@itemize @bullet
+@item libust
+@item libinterfork
+@item libustcomm
+@end itemize
-The accompanying tools of the @acronym{UST} package are licensed as
-@acronym{GNU} @acronym{GPL} v2. These tools include the @file{ustctl} trace
-control program and the @file{ustd} daemon.
+Components licensed as GPL v2:
+@itemize @bullet
+@item ustctl
+@item libustcmd
+@item ustd
+@end itemize
@node Supported platforms
@section Supported platforms
-UST can currently trace applications running on Linux, on the x86-32 and x86-64 architectures.
+UST can currently trace applications running on Linux, on the x86-32, x86-64
+and PowerPC 32 architectures.
@node Installation
@chapter Installation
This contains the tracing library, the ustd daemon, trace control tools
and other helper tools.
-Repository: http://git.dorsal.polymtl.ca
-
-@item
-libkcompat
-
-This is a library that contains a userspace port of some kernel APIs.
-
-Repository: http://git.dorsal.polymtl.ca
+Repository: @url{http://git.dorsal.polymtl.ca}
@item
liburcu
Available in Debian as package liburcu-dev.
-Home page: http://lttng.org/?q=node/18
+Home page: @url{http://lttng.org/urcu}
@item
LTTV
LTTV is a graphical (and text) viewer for LTTng traces.
-Home page: http://lttng.org
+Home page: @url{http://lttng.org}
@end itemize
-Libkcompat and 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.
+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.
@node Markers
@section Markers
-Adding a marker is simply a matter of insert one line in the program.
+Adding a marker is simply a matter of inserting one line in the program.
@example
@verbatim
/* a marker: */
trace_mark(main, myevent, "firstarg %d secondarg %s", v, st);
- /* a marker without arguments: */
+ /* another marker without arguments: */
trace_mark(main, myotherevent, MARK_NOARGS);
return 0;
format strings directly in the code and to have format strings appear more than
once if a given marker is reused.
-@quotation Note Although this example uses @emph{mychannel} as the channel, the
+@quotation Note
+Although this example uses @emph{mychannel} as the channel, the
only channel name currently supported with early tracing is @strong{ust}. The
@command{usttrace} tool always uses the early tracing mode. When using manual
-mode without early tracing, any channel name may be used. @end quotation
+mode without early tracing, any channel name may be used.
+@end quotation
A function instrumented with a tracepoint looks like this:
@verbatim
#include <ust/tracepoint.h>
-DECLARE_TRACE(mychannel_myevent, TPPROTO(int v, char *st),
- TPARGS(v, st));
+DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st),
+ TP_ARGS(v, st));
@end verbatim
@end example
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
-main() function.
+@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
# A column indicates 0 for an inactive marker and 1 for an active marker.
# Enable a marker
-$ ustctl --enable-marker 1234 ust/mymark
+$ ustctl --enable-marker ust/mymark 1234
# Create a trace
$ ustctl --create-trace 1234
@end verbatim
@end example
+For more information about the manual mode, see the ustctl(1) man page.
+
@node Using early tracing
@section Using early tracing
@node Tracing across @code{fork()} and @code{clone()}
@section Tracing across @code{fork()} and @code{clone()}
-Tracing across @code{clone()} when @code{CLONE_VM} is specified is supported
-without any particular action.
+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. @strong{TODO: specify how to do it.}
+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
+@code{fork()} or @code{clone()} with @code{CLONE_VM}. After the call,
+@code{ust_after_fork_parent()} must be called in the parent process and
+@code{ust_after_fork_child()} must be called in the child process.
-This can be done automatically (for @code{fork()} only for now), 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.
@node Tracing programs and libraries that were not linked to libust
@section Tracing programs and libraries that were not linked to libust
-Todo.
+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
+@command{usttrace}'s @option{-l} option. It can also be done by setting the
+@env{LD_PRELOAD} environment variable on the command line. For example:
+
+@example
+@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
+@end verbatim
+@end example
+
@node Performance
@chapter Performance
@node Viewing traces
@chapter Viewing traces
+Traces may be viewed with LTTV. An example of command for launching LTTV is
+given in the quickstart.
+
+@menu
+* Viewing multiple traces::
+* Combined kernel-userspace tracing::
+@end menu
+
+@node Viewing multiple traces
+@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.
+
+@node Combined kernel-userspace tracing
+@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.
+
+@node Resource Usage
+@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
+@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:
+@itemize @bullet
+@item use @code{malloc()} and @code{free()}
+@item map shared memory segment in the process adress space
+@item intercept some library calls, specifically @code{fork()} and @code{clone()}
+@item do interprocess communication with the daemon or ustctl
+@item create and open named sockets
+
+@end itemize
+
+It will not:
+@itemize @bullet
+@item handle any signal (all signals are blocked in the listener thread)
+@item change any process-wide setting that could confuse the application
+@end itemize
+
+@node List of environment variables detected by libust
+@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.
+
+@itemize @bullet
+
+@item
+@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.
+
+@item
+@env{UST_AUTOPROBE}
+
+If set to @code{1}, enable all markers by the time the @code{main()} function starts.
+
+@item
+@env{UST_AUTOCOLLECT}
+
+If set to @code{0}, disable notification of daemon on trace start. Useful for
+performance tests.
+
+@item
+@env{UST_OVERWRITE}
+
+If set to @code{1}, enable overwriting of buffers on overrun.
+
+@item
+@env{UST_SUBBUF_NUM}
+
+If set, defines the default number of subbuffers per buffer.
+
+@item
+@env{UST_SUBBUF_SIZE}
+
+If set, defines the default size of subbuffers, in bytes.
+
+@end itemize
+
+@node GDB integration
+@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
+@command{./configure} script with the @code{-DCONFIG_UST_GDB_INTEGRATION} flag
+in the @env{CFLAGS} environment variable. For example:
+
+@example
+@verbatim
+
+CFLAGS=-DCONFIG_UST_GDB_INTEGRATION ./configure
+
+@end verbatim
+@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.
+
@bye
projects / ust.git / blobdiff