@node Top
@top LTTng Userspace Tracer
-This manual is for UST 0.1.
+This manual is for UST 0.4.
@end ifnottex
@menu
* Recording a trace::
* Viewing traces::
* Performance::
+* Resource Usage::
@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
@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
@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
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 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
+
+
@bye
projects / ust.git / blobdiff