X-Git-Url: http://git.lttng.org/?a=blobdiff_plain;f=doc%2Fmanual.lyx;h=21eb0e144dcdbcd6c4bb13964d1399032634e6c5;hb=d70ba45fb0cd618053a0c51781b1b8529aad085a;hp=310b0c9ed76ed9bf3a71eac0bd1034fe763386ae;hpb=a8afdd3c38a6c7f082ca12965d97eb9bcfc2c6c4;p=ust.git

diff --git a/doc/manual.lyx b/doc/manual.lyx
index 310b0c9..21eb0e1 100644
--- a/doc/manual.lyx
+++ b/doc/manual.lyx
@@ -36,6 +36,7 @@
 \tracking_changes false
 \output_changes false
 \author "" 
+\author "" 
 \end_header
 
 \begin_body
@@ -56,6 +57,20 @@ What is the LTTng Userspace Tracer?
 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
@@ -69,17 +84,145 @@ 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
+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
@@ -87,13 +230,14 @@ Instrumenting an Application
 \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 and 
+ 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 handler may be instrumented as well.
+ Signal handlers may be instrumented as well.
 \end_layout
 
 \begin_layout Standard
@@ -107,6 +251,11 @@ There are two APIs to instrument programs: markers and tracepoints.
 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
@@ -127,7 +276,7 @@ status open
 
 \begin_layout Plain Layout
 
-void function()
+int main(int argc, char **argv)
 \end_layout
 
 \begin_layout Plain Layout
@@ -194,6 +343,15 @@ firstarg %d secondarg %s
 
 \begin_layout Plain Layout
 
+\end_layout
+
+\begin_layout Plain Layout
+
+	return 0;
+\end_layout
+
+\begin_layout Plain Layout
+
 }
 \end_layout
 
@@ -380,49 +538,137 @@ TRACEPOINT_LIB;
 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 Subsection
-Early Tracing
+\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 Section
-Viewing and Analyzing the Trace
+\begin_layout Standard
+In order to record a trace, the daemon must first be started with the following
+ command.
 \end_layout
 
-\begin_layout Section
-Advanced Concepts
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+ustd
 \end_layout
 
-\begin_layout Subsection
-Using Custom Probes
+\end_inset
+
+
 \end_layout
 
-\begin_layout Subsection
-Instrumenting Calls to Library Functions without Recompilation
+\begin_layout Standard
+Markers can be listed with the following command (for PID 1234).
 \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.
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+ust --list-markers 1234
 \end_layout
 
-\begin_layout Subsection
-Tracing Programs Without Linking them to the Tracing Library
+\end_inset
+
+
 \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.
+A marker can be enabled with the following command (for PID 1234).
 \end_layout
 
 \begin_layout Standard
@@ -432,8 +678,7 @@ status open
 
 \begin_layout Plain Layout
 
-LD_PRELOAD=...
- program
+ust --enable-marker ust/mymark 1234
 \end_layout
 
 \end_inset
@@ -441,9 +686,520 @@ LD_PRELOAD=...
 
 \end_layout
 
-\begin_layout Section
-\start_of_appendix
-Format of Marker Format Strings
+\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