X-Git-Url: http://git.lttng.org/?a=blobdiff_plain;f=doc%2Fmanual.lyx;h=21eb0e144dcdbcd6c4bb13964d1399032634e6c5;hb=2944a62989b8466e0d551e37a0be0e8e6cd69905;hp=47e20d6e508137baba8883f5e6042bb7c0b8e643;hpb=0ce2af7f6372336d520847b4745da781344ba743;p=ust.git diff --git a/doc/manual.lyx b/doc/manual.lyx index 47e20d6..21eb0e1 100644 --- a/doc/manual.lyx +++ b/doc/manual.lyx @@ -84,7 +84,7 @@ 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 @@ -96,7 +96,11 @@ Still to implement: \end_layout \begin_layout Itemize -Support of dynamic instrumentation (being implemented in +Support for dynamic instrumentation +\end_layout + +\begin_layout Itemize +Per thread or per CPU buffers \end_layout \begin_layout Standard @@ -112,6 +116,113 @@ A extension to gdb tracepoints that will allow the tracing of applications 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 @@ -126,7 +237,7 @@ In order to record a trace of events occurring in a application, the application \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 @@ -165,7 +276,7 @@ status open \begin_layout Plain Layout -void function() +int main(int argc, char **argv) \end_layout \begin_layout Plain Layout @@ -232,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 @@ -418,14 +538,197 @@ 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 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 @@ -456,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 @@ -497,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 @@ -843,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