+++ /dev/null
-#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 <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
-
-\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
projects / lttng-ust.git / blobdiff