@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}.
+
+Components licensed as LGPL v2.1:
+@itemize @bullet
+@item libust
+@item libinterfork
+@item libustcomm
+@end itemize
+
+Components licensed as GPL v2:
+@itemize @bullet
+@item ustctl
+@item libustcmd
+@item ustd
+@end itemize
+
@node Supported platforms
@section Supported platforms
@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;
@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
# 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
# Stop tracing
$ ustctl --stop-trace 1234
+
+# Destroy the trace
+$ ustctl --destroy-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.
+
@bye
projects / ust.git / blobdiff