X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fmanual.lyx;h=21eb0e144dcdbcd6c4bb13964d1399032634e6c5;hb=62ec620f40891af46d0ee4768992275dc7b28433;hp=13a6e60dacaeb068542f2596733d47aa0dbd3352;hpb=7c2343de7f0d04535565637bbd52653befdc337f;p=ust.git diff --git a/doc/manual.lyx b/doc/manual.lyx index 13a6e60..21eb0e1 100644 --- a/doc/manual.lyx +++ b/doc/manual.lyx @@ -120,6 +120,109 @@ Performance 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 @@ -243,8 +346,8 @@ firstarg %d secondarg %s \end_layout \begin_layout Plain Layout - -return 0; + + return 0; \end_layout \begin_layout Plain Layout @@ -459,10 +562,173 @@ The application should be statically or dynamically linked to libust. 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 @@ -493,7 +759,34 @@ status open \begin_layout Plain Layout -$ UST_TRACE=1 UST_AUTOPROBE=1 ./prog +# 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 @@ -534,6 +827,11 @@ Calls to uninstrumented libraries may be instrumented by creating a wrapper 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 @@ -880,5 +1178,29 @@ floats between c types and trace types. 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