From: Pierre-Marc Fournier Date: Mon, 18 Jan 2010 06:59:53 +0000 (-0500) Subject: Change manual to texinfo format and enhance it X-Git-Tag: v0.1~4 X-Git-Url: http://git.lttng.org/?p=ust.git;a=commitdiff_plain;h=5cd1099a9a3210708ae6f3951cd4a26a68028e6b Change manual to texinfo format and enhance it --- diff --git a/doc/manual.lyx b/doc/manual.lyx deleted file mode 100644 index 21eb0e1..0000000 --- a/doc/manual.lyx +++ /dev/null @@ -1,1206 +0,0 @@ -#LyX 1.6.1 created this file. For more info see http://www.lyx.org/ -\lyxformat 345 -\begin_document -\begin_header -\textclass article -\use_default_options true -\language english -\inputencoding auto -\font_roman default -\font_sans default -\font_typewriter default -\font_default_family default -\font_sc false -\font_osf false -\font_sf_scale 100 -\font_tt_scale 100 - -\graphics default -\paperfontsize default -\use_hyperref false -\papersize default -\use_geometry false -\use_amsmath 1 -\use_esint 1 -\cite_engine basic -\use_bibtopic false -\paperorientation portrait -\secnumdepth 3 -\tocdepth 3 -\paragraph_separation indent -\defskip medskip -\quotes_language english -\papercolumns 1 -\papersides 1 -\paperpagestyle default -\tracking_changes false -\output_changes false -\author "" -\author "" -\end_header - -\begin_body - -\begin_layout Title -LTTng Userspace Tracer Manual -\end_layout - -\begin_layout Author -Pierre-Marc Fournier -\end_layout - -\begin_layout Section -What is the LTTng Userspace Tracer? -\end_layout - -\begin_layout Subsection -Overview -\end_layout - -\begin_layout Standard -The LTTng Userspace Tracer (UST) is a tracing system for userspace applications. - It is designed to trace efficiently applications that produce events at - a very high rate. - UST is derived from LTTng, a tracer for the Linux kernel. - It has the same trace format. -\end_layout - -\begin_layout Standard -Users may choose at runtime and even at trace time what instrumentation - should be activated. - Custom probes may be used to trace events conditionally. -\end_layout - -\begin_layout Subsection -Features -\end_layout - -\begin_layout Itemize -Arbitrary number of channels -\end_layout - -\begin_layout Itemize -One buffer per process (multiple threads share the same buffer) -\end_layout - -\begin_layout Itemize -Early process tracing (from the beginning of the main() function) -\end_layout - -\begin_layout Itemize -Support for custom probes -\end_layout - -\begin_layout Standard -Still to implement: -\end_layout - -\begin_layout Itemize -Support for dynamic instrumentation -\end_layout - -\begin_layout Itemize -Per thread or per CPU buffers -\end_layout - -\begin_layout Standard -Complementary systems: -\end_layout - -\begin_layout Itemize -A extension to gdb tracepoints that will allow the tracing of applications - with dynamic instrumentation is under development. -\end_layout - -\begin_layout Subsection -Performance -\end_layout - -\begin_layout Section -Installation -\end_layout - -\begin_layout Subsection -Obtain the code -\end_layout - -\begin_layout Standard -To compile UST, you need: -\end_layout - -\begin_layout Itemize -the UST code -\end_layout - -\begin_layout Itemize -libkcompat -\end_layout - -\begin_layout Itemize -liburcu-pmf -\end_layout - -\begin_layout Subsection -Configure libkcompat -\end_layout - -\begin_layout Standard -Edit kcompat.h and uncomment the architecture of the target system. -\end_layout - -\begin_layout Subsection -Configure libust -\end_layout - -\begin_layout Standard -If the code was obtained through git, first generate a Makefile by running - autogen.sh. -\end_layout - -\begin_layout Standard -Then, run ./configure, specifying the directories of liburcu and libkcompat. - Example: -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -./configure --with-urcu=/home/pmf/liburcu-pmf --with-kcompat=/home/pmf/libkcompat -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Build liburcu -\end_layout - -\begin_layout Standard -Go to the liburcu directory and run: -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -make -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Build ust -\end_layout - -\begin_layout Standard -Go to the ust directory and run: -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -make -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Section -Instrumenting an Application -\end_layout - -\begin_layout Standard -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. -\end_layout - -\begin_layout Standard -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. -\end_layout - -\begin_layout Standard -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. -\end_layout - -\begin_layout Subsection -Markers -\end_layout - -\begin_layout Standard -Markers were ported from the Linux Kernel Markers implementation. - Therefore, their usage is almost identical. -\end_layout - -\begin_layout Subsubsection -Inserting Markers -\end_layout - -\begin_layout Standard -Adding a marker is simply a matter of insert one line in the program. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -#include -\end_layout - -\begin_layout Plain Layout - -int main(int argc, char **argv) -\end_layout - -\begin_layout Plain Layout - -{ -\end_layout - -\begin_layout Plain Layout - - int v; -\end_layout - -\begin_layout Plain Layout - - char *st; -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - - /* ... - set values of v and st ... - */ -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - - /* a marker: */ -\end_layout - -\begin_layout Plain Layout - - trace_mark(main, myevent, -\begin_inset Quotes eld -\end_inset - -firstarg %d secondarg %s -\begin_inset Quotes erd -\end_inset - -, v, st); -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - - /* a marker without arguments: */ -\end_layout - -\begin_layout Plain Layout - - trace_mark(main, myotherevent, MARK_NOARGS); -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - - return 0; -\end_layout - -\begin_layout Plain Layout - -} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -The invocation of the trace_mark() macro requires at least 3 arguments. - The first, here -\begin_inset Quotes eld -\end_inset - -main -\begin_inset Quotes erd -\end_inset - -, is the name of the event category. - It is also the name of the channel the event will go in. - The second, here -\begin_inset Quotes eld -\end_inset - -myevent -\begin_inset Quotes erd -\end_inset - - 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. -\end_layout - -\begin_layout Standard -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. -\end_layout - -\begin_layout Subsubsection -Registering the Markers -\end_layout - -\begin_layout Standard -In order to inform to register the Markers present in the module, a macro - must be inserted at global scope. - Only one such macro is needed per exacutable or per shared object. - Adding it more than once, however, is harmless. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -MARKER_LIB; -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Tracepoints -\end_layout - -\begin_layout Standard -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. -\end_layout - -\begin_layout Standard -A tracepoint in the code looks like this: -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -#include -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -void function() -\end_layout - -\begin_layout Plain Layout - -{ -\end_layout - -\begin_layout Plain Layout - - int v; -\end_layout - -\begin_layout Plain Layout - - char *st; -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - - /* ... - set values of v and st ... - */ -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - - /* a tracepoint: */ -\end_layout - -\begin_layout Plain Layout - - trace_main_myevent(v, st); -\end_layout - -\begin_layout Plain Layout - -} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -DEFINE_TRACE(); -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -TRACEPOINT_LIB; -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Compiling the Application -\end_layout - -\begin_layout Standard -See the -\begin_inset Quotes eld -\end_inset - -hello -\begin_inset Quotes erd -\end_inset - - directory for an example application and makefile. -\end_layout - -\begin_layout Itemize -The compiler must have access to the include path for the libust headers. -\end_layout - -\begin_layout Itemize -The application should be statically or dynamically linked to libust. -\end_layout - -\begin_layout Section -Recording a Trace -\end_layout - -\begin_layout Standard -These preliminary steps need to be done before recording a trace. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -Create the directory for the communication sockets. - Eventually this should be somewhere in /var. -\end_layout - -\begin_layout Plain Layout - -$ mkdir /tmp/socks -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -Create the directory where ustd will write the trace. - This will become configurable. -\end_layout - -\begin_layout Plain Layout - -$ mkdir /tmp/trace -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -Start the daemon -\end_layout - -\begin_layout Plain Layout - -$ ustd -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Basic Recording -\end_layout - -\begin_layout Standard -Tracing on a running program is controlled with the ust helper program. - Ust can start the tracing, stop the tracing, enable markers, disable markers - and list the markers. - Another program, ustd, is a daemon that collects the trace events and write - them to a file. -\end_layout - -\begin_layout Standard -In order to record a trace, the daemon must first be started with the following - command. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -ustd -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -Markers can be listed with the following command (for PID 1234). -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -ust --list-markers 1234 -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -A marker can be enabled with the following command (for PID 1234). -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -ust --enable-marker ust/mymark 1234 -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -Then, the trace can be started. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -ust --start-trace 1234 -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -Eventually it can be stopped and destroyed. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -ust --stop-trace 1234 -\end_layout - -\begin_layout Plain Layout - -ust --destroy-trace 1234 -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Early Tracing -\end_layout - -\begin_layout Standard -Sometimes, an application must be traced as soon as it is started. - In these cases, the Basic Recording method is not satisfactory, as important - events may be lost before the tracing is started. -\end_layout - -\begin_layout Standard -By using the Early Tracing method, it is guaranteed that the tracing is - started when the execution of the main() function of the program starts. -\end_layout - -\begin_layout Standard -Early Tracing may be enabled by defining the UST_TRACE environment variable - to a non-empty value when the program starts. - Additionally, the UST_AUTOPROBE may be set to a non-empty value to automaticall -y connect all markers to the default probe. - For example: -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -# In another terminal, start the daemon. -\end_layout - -\begin_layout Plain Layout - -ustd -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -# Start -\begin_inset Quotes eld -\end_inset - -prog -\begin_inset Quotes erd -\end_inset - - with early tracing. -\end_layout - -\begin_layout Plain Layout - -UST_TRACE=1 UST_AUTOPROBE=1 ./prog -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -In order for the trace to be saved, ustd must be running when the traced - program is started. -\end_layout - -\begin_layout Section -Viewing and Analyzing the Trace -\end_layout - -\begin_layout Standard -LTTV may be used for opening the trace. - If an appropriate time source was used, it may be opened concurrently with - other application traces and kernel traces. -\end_layout - -\begin_layout Section -Advanced Concepts -\end_layout - -\begin_layout Subsection -Using Custom Probes for Conditional Tracing -\end_layout - -\begin_layout Subsection -Instrumenting Calls to Library Functions without Recompilation -\end_layout - -\begin_layout Standard -Calls to uninstrumented libraries may be instrumented by creating a wrapper - library that intercepts calls to the library, trigger an instrumentation - point. -\end_layout - -\begin_layout Standard -Such an example can be found in the libmallocwrap directory of the ust code - package. -\end_layout - -\begin_layout Subsection -Tracing Programs Without Linking them to the Tracing Library -\end_layout - -\begin_layout Standard -Programs that were not instrumented nor linked with the tracing libraries - may still be traced. - In order to produce events, they must be linked to instrumented libraries - or use instrumented library wrappers as described in section xx. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -LD_PRELOAD=... - program -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Section -\start_of_appendix -Format of Marker Format Strings -\end_layout - -\begin_layout Standard -The format of Marker format strings is inspired from printf() format strings. - As with printf(), it is used to indicate to the parsing function the type - of the arguments that are passed. - Additionally, format strings indicate the name of each argument and the - format of that argument in the trace. - The structure of a typical format string is the following. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -\begin_inset Quotes eld -\end_inset - -field_name1 #tracetype1 %ctype1 field_name2 #tracetype2 %ctype2 -\begin_inset Quotes erd -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Description -field_name: The name of the field, as it will be seen when the trace is - parsed. -\end_layout - -\begin_layout Description -tracetype: The type of the argument as it will be written in the trace. -\end_layout - -\begin_layout Description -ctype: The C type of the argument passed to the Marker (this is very similar - to the %... - types in a printf() format string) -\end_layout - -\begin_layout Standard -Both field_name and tracetype are optional. - These are all valid format strings: -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -tracetype -\end_layout - -\begin_layout Standard -A typical Marker format string looks like this: -\end_layout - -\begin_layout Standard -The serialization format string supports the basic printf format strings. -\end_layout - -\begin_layout Standard -In addition, it defines new formats that can be used to serialize more -\end_layout - -\begin_layout Standard -complex/non portable data structures. -\end_layout - -\begin_layout Standard -Typical use: -\end_layout - -\begin_layout Standard -field_name %ctype -\end_layout - -\begin_layout Standard -field_name #tracetype %ctype -\end_layout - -\begin_layout Standard -field_name #tracetype %ctype1 %ctype2 ... -\end_layout - -\begin_layout Standard -A conversion is performed between format string types supported by GCC and -\end_layout - -\begin_layout Standard -the trace type requested. - GCC type is used to perform type checking on format -\end_layout - -\begin_layout Standard -strings. - Trace type is used to specify the exact binary representation -\end_layout - -\begin_layout Standard -in the trace. - A mapping is done between one or more GCC types to one trace -\end_layout - -\begin_layout Standard -type. - Sign extension, if required by the conversion, is performed following -\end_layout - -\begin_layout Standard -the trace type. -\end_layout - -\begin_layout Standard -If a gcc format is not declared with a trace format, the gcc format is -\end_layout - -\begin_layout Standard -also used as binary representation in the trace. -\end_layout - -\begin_layout Standard -Strings are supported with %s. -\end_layout - -\begin_layout Standard -A single tracetype (sequence) can take multiple c types as parameter. -\end_layout - -\begin_layout Standard -c types: -\end_layout - -\begin_layout Standard -see printf(3). -\end_layout - -\begin_layout Standard -Note: to write a uint32_t in a trace, the following expression is recommended -\end_layout - -\begin_layout Standard -si it can be portable: -\end_layout - -\begin_layout Standard -("#4u%lu", (unsigned long)var) -\end_layout - -\begin_layout Standard -trace types: -\end_layout - -\begin_layout Standard -Serialization specific formats : -\end_layout - -\begin_layout Standard -Fixed size integers -\end_layout - -\begin_layout Standard -#1u writes uint8_t -\end_layout - -\begin_layout Standard -#2u writes uint16_t -\end_layout - -\begin_layout Standard -#4u writes uint32_t -\end_layout - -\begin_layout Standard -#8u writes uint64_t -\end_layout - -\begin_layout Standard -#1d writes int8_t -\end_layout - -\begin_layout Standard -#2d writes int16_t -\end_layout - -\begin_layout Standard -#4d writes int32_t -\end_layout - -\begin_layout Standard -#8d writes int64_t -\end_layout - -\begin_layout Standard -i.e.: -\end_layout - -\begin_layout Standard -#1u%lu #2u%lu #4d%lu #8d%lu #llu%hu #d%lu -\end_layout - -\begin_layout Standard -* Attributes: -\end_layout - -\begin_layout Standard -n: (for network byte order) -\end_layout - -\begin_layout Standard -#ntracetype%ctype -\end_layout - -\begin_layout Standard -is written in the trace in network byte order. -\end_layout - -\begin_layout Standard -i.e.: #bn4u%lu, #n%lu, #b%u -\end_layout - -\begin_layout Standard -TODO (eventually) -\end_layout - -\begin_layout Standard -Variable length sequence -\end_layout - -\begin_layout Standard -#a #tracetype1 #tracetype2 %array_ptr %elem_size %num_elems -\end_layout - -\begin_layout Standard -In the trace: -\end_layout - -\begin_layout Standard -#a specifies that this is a sequence -\end_layout - -\begin_layout Standard -#tracetype1 is the type of elements in the sequence -\end_layout - -\begin_layout Standard -#tracetype2 is the type of the element count -\end_layout - -\begin_layout Standard -GCC input: -\end_layout - -\begin_layout Standard -array_ptr is a pointer to an array that contains members of size -\end_layout - -\begin_layout Standard -elem_size. -\end_layout - -\begin_layout Standard -num_elems is the number of elements in the array. -\end_layout - -\begin_layout Standard -i.e.: #a #lu #lu %p %lu %u -\end_layout - -\begin_layout Standard -Callback -\end_layout - -\begin_layout Standard -#k callback (taken from the probe data) -\end_layout - -\begin_layout Standard -The following % arguments are exepected by the callback -\end_layout - -\begin_layout Standard -i.e.: #a #lu #lu #k %p -\end_layout - -\begin_layout Standard -Note: No conversion is done from floats to integers, nor from integers to -\end_layout - -\begin_layout Standard -floats between c types and trace types. - float conversion from double to float -\end_layout - -\begin_layout Standard -or from float to double is also not supported. -\end_layout - -\begin_layout Section -Environment variables -\end_layout - -\begin_layout Standard -The following environment variables change the behavior of libust. -\end_layout - -\begin_layout Description -UST_TRACE When defined, automatically enables tracing. -\end_layout - -\begin_layout Description -UST_AUTOPROBE When value is 1, enable all markers automatically. - When value is a regular expression, enable all markers whose name matches - the regular expression. -\end_layout - -\begin_layout Description -UST_DAEMON_SOCKET If not set, the default location of the daemon socket - is used. - If set, the value is used as path to the ustd socket. -\end_layout - -\end_body -\end_document diff --git a/doc/manual/.gitignore b/doc/manual/.gitignore new file mode 100644 index 0000000..2460008 --- /dev/null +++ b/doc/manual/.gitignore @@ -0,0 +1 @@ +!Makefile diff --git a/doc/manual/Makefile b/doc/manual/Makefile new file mode 100644 index 0000000..62a430f --- /dev/null +++ b/doc/manual/Makefile @@ -0,0 +1,4 @@ +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 new file mode 100644 index 0000000..b0b588d --- /dev/null +++ b/doc/manual/manual.texinfo @@ -0,0 +1,437 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ust.info +@settitle LTTng Userspace Tracer (UST) Manual +@c %**end of header + +@copying +This manual is for program, version version. + +Copyright @copyright{} copyright-owner. + +@quotation +Permission is granted to ... +@end quotation +@end copying + +@titlepage +@title LTTng Userspace Tracer (UST) Manual +@c @subtitle subtitle-if-any +@c @subtitle second-subtitle +@c @author author + +@c The following two commands +@c start the copyright page. +@c @page +@c @vskip 0pt plus 1filll +@c @insertcopying + +@c Published by ... +@end titlepage + +@c So the toc is printed at the start. +@contents + +@ifnottex +@node Top +@top LTTng Userspace Tracer + +This manual is for UST 0.1. +@end ifnottex + +@menu +* Overview:: +* Installation:: +* Quick start:: +* Instrumenting an application:: +* Recording a trace:: +* Viewing traces:: +* Performance:: +@c * Copying:: Your rights and freedoms. +@end menu + +@node Overview +@chapter Overview + +@menu +* Supported platforms:: +@end menu + +@node Supported platforms +@section Supported platforms + +UST can currently trace applications running on Linux, on the x86-32 and x86-64 architectures. + +@node Installation +@chapter Installation + +The LTTng userspace tracer is a library and a set of userspace tools. + +The following packages are required: + +@itemize @bullet +@item +ust + +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 + +@item +liburcu + +This is the userspace read-copy update library by Mathieu Desnoyers. + +Available in Debian as package liburcu-dev. + +Home page: http://lttng.org/?q=node/18 + +@item +LTTV + +LTTV is a graphical (and text) viewer for LTTng traces. + +Home page: 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. + +Refer to the README in each of these packages for installation instructions. + +@c @menu +@c @end menu + +@node Quick start +@chapter Quick start + +First, instrument a program with a marker. + +@example +@verbatim + +#include + +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; +} + +@end verbatim +@end example + +Then compile it in the regular way, linking it with libust. For example: + +@example +gcc -o foo -lust foo.c +@end example + +Run the program with @command{usttrace}. The @command{usttrace} output says where the trace +was written. + +@example +usttrace ./foo +@end example + +Finally, open the trace in LTTV. + +@example +lttv-gui -t /path/to/trace +@end example + +The trace can also be dumped as text in the console: + +@example +lttv -m textDump -t /path/to/trace +@end example + +@node Instrumenting an application +@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. + +@menu +* Markers:: +* Tracepoints:: +@end menu + +@node Markers +@section Markers + +Adding a marker is simply a matter of insert one line in the program. + +@example +@verbatim +#include + +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); + + /* a marker without arguments: */ + trace_mark(main, myotherevent, MARK_NOARGS); + + return 0; +} +@end verbatim +@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. + +@node Tracepoints +@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. + +@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 + +A function instrumented with a tracepoint looks like this: + +@example +@verbatim +#include "tp.h" + +void function() +{ + int v; + char *st; + + /* ... set values of v and st ... */ + + /* a tracepoint: */ + trace_mychannel_myevent(v, st); +} +@end verbatim +@end example + +Another file, here tp.h, contains declarations for the tracepoint. + +@example +@verbatim +#include + +DECLARE_TRACE(mychannel_myevent, TPPROTO(int v, char *st), + TPARGS(v, st)); +@end verbatim +@end example + +A third file, here tp.c, contains definitions for the tracepoint. + +@example +@verbatim +#include +#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); +} +@end verbatim +@end example + +Here, tp.h and tp.c could contain declarations and definitions for other +tracepoints. The constructor would contain other register_* calls. + +@node Recording a trace +@chapter Recording a trace + +@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:: +@end menu + +@node Using @command{usttrace} +@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: +@itemize @bullet +@item creates a daemon +@item enables all markers +@item runs the command specified on the command line +@item after the command ends, prints the location where the trace was saved +@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 +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. + +@node Setting up the recording manually +@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. + +@example +@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 1234 ust/mymark + +# Create a trace +$ ustctl --create-trace 1234 + +# Start tracing +$ ustctl --start-trace 1234 + +# Do things... + +# Stop tracing +$ ustctl --stop-trace 1234 +@end verbatim +@end example + +@node Using early tracing +@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. + + +@node Crash recovery +@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. + +@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. + +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.} + +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. + +@node Performance +@chapter Performance + +Todo. + +@node Viewing traces +@chapter Viewing traces + +@bye