[lttng-ust.git] / doc / manual.lyx

#LyX 1.6.2 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 <marker.h>
\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 <marker.h>
\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

\end_body
\end_document