* Nils Carlson ([email protected]) wrote: > Fix so that info is built using automake and also clean up the > automake process so that make clean works.
This makes sense! Thanks, Acked-by: Mathieu Desnoyers <[email protected]> > > Signed-off-by: Nils Carlson <[email protected]> > --- > .gitignore | 1 + > configure.ac | 2 + > doc/Makefile.am | 3 +- > doc/info/Makefile.am | 2 + > doc/info/ust.texi | 634 > +++++++++++++++++++++++++++++++++++++++++++++ > doc/man/Makefile.am | 2 + > doc/manual/.gitignore | 1 - > doc/manual/Makefile | 4 - > doc/manual/manual.texinfo | 634 > --------------------------------------------- > 9 files changed, 642 insertions(+), 641 deletions(-) > create mode 100644 doc/info/Makefile.am > create mode 100644 doc/info/ust.texi > create mode 100644 doc/man/Makefile.am > delete mode 100644 doc/manual/.gitignore > delete mode 100644 doc/manual/Makefile > delete mode 100644 doc/manual/manual.texinfo > > diff --git a/.gitignore b/.gitignore > index 4896a47..020c2f4 100644 > --- a/.gitignore > +++ b/.gitignore > @@ -10,6 +10,7 @@ Makefile > *.lo > Makefile.in > *.loT > +*.info > configure > aclocal.m4 > autom4te.cache/ > diff --git a/configure.ac b/configure.ac > index 922e626..4fcd565 100644 > --- a/configure.ac > +++ b/configure.ac > @@ -107,6 +107,8 @@ AC_MSG_RESULT($LIBFORMAT) > AC_CONFIG_FILES([ > Makefile > doc/Makefile > + doc/man/Makefile > + doc/info/Makefile > include/Makefile > libust/Makefile > tests/Makefile > diff --git a/doc/Makefile.am b/doc/Makefile.am > index fa769be..37a55ac 100644 > --- a/doc/Makefile.am > +++ b/doc/Makefile.am > @@ -1,2 +1 @@ > -EXTRA_DIST = manual man/ustctl.1 man/ustd.1 man/usttrace.1 > -man_MANS = man/ustctl.1 man/ustd.1 man/usttrace.1 > +SUBDIRS = man info > \ No newline at end of file > diff --git a/doc/info/Makefile.am b/doc/info/Makefile.am > new file mode 100644 > index 0000000..93d1896 > --- /dev/null > +++ b/doc/info/Makefile.am > @@ -0,0 +1,2 @@ > +EXTRA_DIST = ust.texi > +info_TEXINFOS = ust.texi > diff --git a/doc/info/ust.texi b/doc/info/ust.texi > new file mode 100644 > index 0000000..e0565f3 > --- /dev/null > +++ b/doc/info/ust.texi > @@ -0,0 +1,634 @@ > +\input texinfo @c -*-texinfo-*- > +...@c %**start of header > +...@setfilename ust.info > +...@settitle LTTng Userspace Tracer (UST) Manual > +...@c %**end of header > + > +...@copying > +This manual is for program, version version. > + > +Copyright @copyright{} copyright-owner. > + > +...@quotation > +Permission is granted to ... > +...@end quotation > +...@end copying > + > +...@titlepage > +...@title LTTng Userspace Tracer (UST) Manual > +...@c @subtitle subtitle-if-any > +...@c @subtitle second-subtitle > +...@c @author author > + > +...@c The following two commands > +...@c start the copyright page. > +...@c @page > +...@c @vskip 0pt plus 1filll > +...@c @insertcopying > + > +...@c Published by ... > +...@end titlepage > + > +...@c So the toc is printed at the start. > +...@contents > + > +...@ifnottex > +...@node Top > +...@top LTTng Userspace Tracer > + > +This manual is for UST 0.5. > +...@end ifnottex > + > +...@menu > +* Overview:: > +* Installation:: > +* Quick start:: > +* Instrumenting an application:: > +* Recording a trace:: > +* Viewing traces:: > +* Performance:: > +* Resource Usage:: > +* List of environment variables detected by libust:: > +* GDB integration:: > +...@c * Copying:: Your rights and freedoms. > +...@end menu > + > +...@node Overview > +...@chapter Overview > + > +...@menu > +* What is UST?:: > +* License:: > +* Supported platforms:: > +...@end menu > + > +...@node What is UST? > +...@section What is UST? > + > +The LTTng Userspace Tracer (UST) is a library accompanied by a set of tools > to > +trace userspace code. > + > +Code may be instrumented with either markers or tracepoints. A highly > efficient > +lockless tracer records these events to a trace buffers. These buffers are > reaped > +by a deamon which writes trace data to disk. > + > +High performance is achieved by the use of lockless buffering algorithms, > RCU and > +per-cpu buffers. In addition, special care is taken to minize cache impact. > + > +...@node License > +...@section License > +The LTTng Userspace Tracer is intended to be linkable to open source software > +as well as to proprietary applications. This was accomplished by licensing > +the code that needs to be linked to the traced program as @acronym{LGPL}. > + > +Components licensed as LGPL v2.1: > +...@itemize @bullet > +...@item libust > +...@item libinterfork > +...@item libustcomm > +...@end itemize > + > +Components licensed as GPL v2: > +...@itemize @bullet > +...@item ustctl > +...@item libustcmd > +...@item ustd > +...@end itemize > + > +...@node Supported platforms > +...@section Supported platforms > + > +UST can currently trace applications running on Linux, on the x86-32, x86-64 > +and PowerPC 32 architectures. > + > +...@node Installation > +...@chapter Installation > + > +The LTTng userspace tracer is a library and a set of userspace tools. > + > +The following packages are required: > + > +...@itemize @bullet > +...@item > +ust > + > +This contains the tracing library, the ustd daemon, trace control tools > +and other helper tools. > + > +Repository: @url{http://git.dorsal.polymtl.ca} > + > +...@item > +liburcu > + > +This is the userspace read-copy update library by Mathieu Desnoyers. > + > +Available in Debian as package liburcu-dev. > + > +Home page: @url{http://lttng.org/urcu} > + > +...@item > +LTTV > + > +LTTV is a graphical (and text) viewer for LTTng traces. > + > +Home page: @url{http://lttng.org} > + > +...@end itemize > + > +Liburcu should be installed first. UST may then be compiled and installed. > LTTV > +has no dependency on the other packages; it may therefore be installed on a > +system which does not have UST installed. > + > +Refer to the README in each of these packages for installation instructions. > + > +...@c @menu > +...@c @end menu > + > +...@node Quick start > +...@chapter Quick start > + > +First, instrument a program with a marker. > + > +...@example > +...@verbatim > + > +#include <ust/marker.h> > + > +int main(int argc, char **argv) > +{ > + int v; > + char *st; > + > + /* ... set values of v and st ... */ > + > + /* a marker: */ > + trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st); > + > + /* a marker without arguments: */ > + trace_mark(ust, myotherevent, MARK_NOARGS); > + > + return 0; > +} > + > +...@end verbatim > +...@end example > + > +Then compile it in the regular way, linking it with libust. For example: > + > +...@example > +gcc -o foo -lust foo.c > +...@end example > + > +Run the program with @command{usttrace}. The @command{usttrace} output says > where the trace > +was written. > + > +...@example > +usttrace ./foo > +...@end example > + > +Finally, open the trace in LTTV. > + > +...@example > +lttv-gui -t /path/to/trace > +...@end example > + > +The trace can also be dumped as text in the console: > + > +...@example > +lttv -m textDump -t /path/to/trace > +...@end example > + > +...@node Instrumenting an application > +...@chapter Instrumenting an application > + > +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. > + > +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. > + > +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. > + > +In addition to executable programs, shared libraries may also be instrumented > +with the methods described in this chapter. > + > +...@menu > +* Markers:: > +* Tracepoints:: > +...@end menu > + > +...@node Markers > +...@section Markers > + > +Adding a marker is simply a matter of inserting one line in the program. > + > +...@example > +...@verbatim > +#include <ust/marker.h> > + > +int main(int argc, char **argv) > +{ > + int v; > + char *st; > + > + /* ... set values of v and st ... */ > + > + /* a marker: */ > + trace_mark(main, myevent, "firstarg %d secondarg %s", v, st); > + > + /* another marker without arguments: */ > + trace_mark(main, myotherevent, MARK_NOARGS); > + > + return 0; > +} > +...@end verbatim > +...@end example > + > +The invocation of the trace_mark() macro requires at least 3 arguments. The > +first, here "main", is the name of the event category. It is also the name of > +the channel the event will go in. The second, here "myevent" 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. > + > +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. > + > +...@node Tracepoints > +...@section Tracepoints > + > +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. > + > +...@quotation Note > +Although this example uses @emph{mychannel} as the channel, the > +only channel name currently supported with early tracing is @strong{ust}. The > +...@command{usttrace} tool always uses the early tracing mode. When using > manual > +mode without early tracing, any channel name may be used. > +...@end quotation > + > +A function instrumented with a tracepoint looks like this: > + > +...@example > +...@verbatim > +#include "tp.h" > + > +void function() > +{ > + int v; > + char *st; > + > + /* ... set values of v and st ... */ > + > + /* a tracepoint: */ > + trace_mychannel_myevent(v, st); > +} > +...@end verbatim > +...@end example > + > +Another file, here tp.h, contains declarations for the tracepoint. > + > +...@example > +...@verbatim > +#include <ust/tracepoint.h> > + > +DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st), > + TP_ARGS(v, st)); > +...@end verbatim > +...@end example > + > +A third file, here tp.c, contains definitions for the tracepoint. > + > +...@example > +...@verbatim > +#include <ust/marker.h> > +#include "tp.h" > + > +DEFINE_TRACE(mychannel_myevent); > + > +void mychannel_myevent_probe(int v, char *st) > +{ > + trace_mark(mychannel, myevent, "v %d st %s", v, st); > +} > + > +static void __attribute__((constructor)) init() > +{ > + register_trace_mychannel_myevent(mychannel_myevent_probe); > +} > +...@end verbatim > +...@end example > + > +Here, tp.h and tp.c could contain declarations and definitions for other > +tracepoints. The constructor would contain other register_* calls. > + > +...@node Recording a trace > +...@chapter Recording a trace > + > +...@menu > +* Using @command{usttrace}:: > +* Setting up the recording manually:: > +* Using early tracing:: > +* Crash recovery:: > +* Tracing across @code{fork()} and @code{clone()}:: > +* Tracing programs and libraries that were not linked to libust:: > +...@end menu > + > +...@node Using @command{usttrace} > +...@section Using @command{usttrace} > + > +The simplest way to record a trace is to use the @command{usttrace} script. > An > +example is given in the quickstart above. > + > +The @command{usttrace} script automatically: > +...@itemize @bullet > +...@item creates a daemon > +...@item enables all markers > +...@item runs the command specified on the command line > +...@item after the command ends, prints the location where the trace was > saved > +...@end itemize > + > +Each subdirectory of the save location contains the trace of one process that > +was generated by the command. The name of a subdirectory consists in the the > PID > +of the process, followed by the timestamp of its creation. > + > +The save location also contains logs of the tracing. > + > +When using @command{usttrace}, the early tracing is always active, which > means > +that the tracing is guaranteed to be started by the time the process enters > its > +...@code{main()} function. > + > +Several @command{usttrace}'s may be run simultaneously without risk of > +conflict. This facilitates the use of the tracer by idependent users on a > +system. Each instance of @command{usttrace} starts its own daemon which > +collects the events of the processes it creates. > + > +...@node Setting up the recording manually > +...@section Setting up the recording manually > + > +Instead of using @command{usttrace}, a trace may be recorded on an already > +running process. > + > +First the daemon must be started. > + > +...@example > +...@verbatim > +# Make sure the directory for the communication sockets exists. > +$ mkdir /tmp/ustsocks > + > +# Make sure the directory where ustd will write the trace exists. > +$ mkdir /tmp/trace > + > +# Start the daemon > +$ ustd > + > +# We assume the program we want to trace is already running and that > +# it has pid 1234. > + > +# List the available markers > +$ ustctl --list-markers 1234 > +# A column indicates 0 for an inactive marker and 1 for an active marker. > + > +# Enable a marker > +$ ustctl --enable-marker ust/mymark 1234 > + > +# Create a trace > +$ ustctl --create-trace 1234 > + > +# Start tracing > +$ ustctl --start-trace 1234 > + > +# Do things... > + > +# Stop tracing > +$ ustctl --stop-trace 1234 > + > +# Destroy the trace > +$ ustctl --destroy-trace 1234 > +...@end verbatim > +...@end example > + > +For more information about the manual mode, see the ustctl(1) man page. > + > +...@node Using early tracing > +...@section Using early tracing > + > +Early tracing consists in starting the tracing as early as possible in the > +program, so no events are lost between program start and the point where the > +command to start the tracing is given. When using early tracing, it is > +guaranteed that by the time the traced program enters its @code{main()} > +function, the tracing will be started. > + > +When using @command{usttrace}, the early tracing is always active. > + > +When using the manual mode (@command{ustctl}), early tracing is enabled using > +environment variables. Setting @env{UST_TRACE} to @code{1}, enables early > +tracing, while setting @env{UST_AUTOPROBE} to @code{1} enables all markers > +automatically. > + > + > +...@node Crash recovery > +...@section Crash recovery > + > +When a process being traced crashes, the daemon is able to recover all the > +events in its buffers that were successfully commited. This is possible > because > +the buffers are in a shared memory segment which remains available to the > +daemon even after the termination of the traced process. > + > +...@node Tracing across @code{fork()} and @code{clone()} > +...@section Tracing across @code{fork()} and @code{clone()} > + > +Tracing across @code{clone()} when the @code{CLONE_VM} flag is specified is > +supported without any particular action. > + > +When @code{clone()} is called without @code{CLONE_VM} or @code{fork()} is > +called, a new address space is created and the tracer must be notified to > +create new buffers for it. > + > +This can be done automatically, by @env{LD_PRELOAD}'ing > @file{libinterfork.so}. > +This library intercepts calls to @code{fork()} and informs the tracer it is > +being called. When using @command{usttrace}, this is accomplied by specifying > +the @option{-f} command line argument. > + > +Alternatively, the program can call @code{ust_before_fork()} before calling > +...@code{fork()} or @code{clone()} with @code{CLONE_VM}. After the call, > +...@code{ust_after_fork_parent()} must be called in the parent process and > +...@code{ust_after_fork_child()} must be called in the child process. > + > + > +...@node Tracing programs and libraries that were not linked to libust > +...@section Tracing programs and libraries that were not linked to libust > + > +Some programs need to be traced even though they were not linked to libust > +either because they were not instrumented or because it was not practical. > + > +An executable that is not instrumented can still yield interesting traces > when > +at least one of its dynamic libraries is instrumented. It is also possible to > +trace certain function calls by intercepting them with a specially crafted > +library that is linked with @env{LD_PRELOAD} at program start. > + > +In any case, a program that was not linked to libust at compile time must be > +linked to it at run time with @env{LD_PRELOAD}. This can be accomplished with > +...@command{usttrace}'s @option{-l} option. It can also be done by setting > the > +...@env{ld_preload} environment variable on the command line. For example: > + > +...@example > +...@verbatim > +# Run ls with usttrace, LD_PRELOAD'ing libust > +# (assuming one of the libraries used by ls is instrumented). > +$ usttrace -l ls > + > +# Run ls, manually adding the LD_PRELOAD. > +$ LD_PRELOAD=/usr/local/lib/libust.so.0 ls > +...@end verbatim > +...@end example > + > + > +...@node Performance > +...@chapter Performance > + > +Todo. > + > +...@node Viewing traces > +...@chapter Viewing traces > + > +Traces may be viewed with LTTV. An example of command for launching LTTV is > +given in the quickstart. > + > +...@menu > +* Viewing multiple traces:: > +* Combined kernel-userspace tracing:: > +...@end menu > + > +...@node Viewing multiple traces > +...@section Viewing multiple traces > + > +When tracing multi-process applications or several applications > simultaneously, > +more than one trace will be obtained. LTTV can open and display all these > +traces simultaneously. > + > +...@node Combined kernel-userspace tracing > +...@section Combined kernel-userspace tracing > + > +In addition to multiple userspace traces, LTTV can open a kernel trace > recorded > +with the LTTng kernel tracer. This provides events that enable the rendering > of > +the Control Flow View and the Resource View. > + > +When doing so, it is necessary to use the same time source for the kernel > +tracer as well as the userspace tracer. Currently, the recommended method is > to > +use the timestamp counter for both. The TSC can however only be used on > architectures > +where it is synchronized across cores. > + > +...@node Resource Usage > +...@chapter Resource Usage > + > +The purpose of this section is to give an overview of the resource usage of > libust. For > +a developer, knowing this can be important: because libust is linked with > applications, it > +needs to share some resources with it. Some applications may make some > assumptions that are in > +conflict with libust's usage of resources. > + > +In practice however, libust is designed to be transparent and is compatible > +with the vast majority of applications. This means no changes are required in > +the application (or library) being linked to libust. > + > +Libust is initialized by a constructor, which by definition runs before the > +...@code{main()} function of the application starts. This constructor > creates a > +thread called the @emph{listener thread}. The listener thread initializes a > +named socket and waits for connections for ustd or ustctl. > + > +Libust-specific code may: > +...@itemize @bullet > +...@item use @code{malloc()} and @code{free()} > +...@item map shared memory segment in the process adress space > +...@item intercept some library calls, specifically @code{fork()} and > @code{clone()} > +...@item do interprocess communication with the daemon or ustctl > +...@item create and open named sockets > + > +...@end itemize > + > +It will not: > +...@itemize @bullet > +...@item handle any signal (all signals are blocked in the listener thread) > +...@item change any process-wide setting that could confuse the application > +...@end itemize > + > +...@node List of environment variables detected by libust > +...@appendix List of environment variables detected by libust > + > +The behavior of tracing can be influenced by setting special environment > +variables in the environment of the traced application. This section > +describes these variables. > + > +...@itemize @bullet > + > +...@item > +...@env{ust_trace} > + > +If set to 1, start tracing as soon as the program starts. Tracing is > +guaranteed to be started by the time the @code{main()} function starts. > + > +...@item > +...@env{ust_autoprobe} > + > +If set to @code{1}, enable all markers by the time the @code{main()} > function starts. > + > +...@item > +...@env{ust_autocollect} > + > +If set to @code{0}, disable notification of daemon on trace start. Useful for > +performance tests. > + > +...@item > +...@env{ust_overwrite} > + > +If set to @code{1}, enable overwriting of buffers on overrun. > + > +...@item > +...@env{ust_subbuf_num} > + > +If set, defines the default number of subbuffers per buffer. > + > +...@item > +...@env{ust_subbuf_size} > + > +If set, defines the default size of subbuffers, in bytes. > + > +...@end itemize > + > +...@node GDB integration > +...@appendix GDB integration > + > +GDB, the GNU Debugger, can use UST markers as GDB tracepoints (note GDB has > its > +own concept of tracepoint). This feature is called GDB Static Tracepoints. > When > +a GDB tracepoint is hit, GDB collects the marker arguments, as well as the > +state of the registers. > + > +In UST, support for GDB integration is not compiled in by default because of > +the cost of saving registers when a marker is hit. To enable it, run the > +...@command{./configure} script with the @code{-DCONFIG_UST_GDB_INTEGRATION} > flag > +in the @env{CFLAGS} environment variable. For example: > + > +...@example > +...@verbatim > + > +CFLAGS=-DCONFIG_UST_GDB_INTEGRATION ./configure > + > +...@end verbatim > +...@end example > + > +As of this writing, GDB Static Tracepoints have been submitted > +(@url{http://sourceware.org/ml/gdb-patches/2010-06/msg00592.html}) to the GDB > +mailing list. > + > +GDB integration is currently only supported on x86-32 and x86-64. > + > +...@bye > diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am > new file mode 100644 > index 0000000..7e18b8e > --- /dev/null > +++ b/doc/man/Makefile.am > @@ -0,0 +1,2 @@ > +EXTRA_DIST = ustctl.1 ustd.1 usttrace.1 > +man_MANS = ustctl.1 ustd.1 usttrace.1 > diff --git a/doc/manual/.gitignore b/doc/manual/.gitignore > deleted file mode 100644 > index 2460008..0000000 > --- a/doc/manual/.gitignore > +++ /dev/null > @@ -1 +0,0 @@ > -!Makefile > diff --git a/doc/manual/Makefile b/doc/manual/Makefile > deleted file mode 100644 > index 62a430f..0000000 > --- a/doc/manual/Makefile > +++ /dev/null > @@ -1,4 +0,0 @@ > -all: ust.html > - > -ust.html: manual.texinfo > - makeinfo --html --no-split manual.texinfo > diff --git a/doc/manual/manual.texinfo b/doc/manual/manual.texinfo > deleted file mode 100644 > index e0565f3..0000000 > --- a/doc/manual/manual.texinfo > +++ /dev/null > @@ -1,634 +0,0 @@ > -\input texinfo @c -*-texinfo-*- > -...@c %**start of header > -...@setfilename ust.info > -...@settitle LTTng Userspace Tracer (UST) Manual > -...@c %**end of header > - > -...@copying > -This manual is for program, version version. > - > -Copyright @copyright{} copyright-owner. > - > -...@quotation > -Permission is granted to ... > -...@end quotation > -...@end copying > - > -...@titlepage > -...@title LTTng Userspace Tracer (UST) Manual > -...@c @subtitle subtitle-if-any > -...@c @subtitle second-subtitle > -...@c @author author > - > -...@c The following two commands > -...@c start the copyright page. > -...@c @page > -...@c @vskip 0pt plus 1filll > -...@c @insertcopying > - > -...@c Published by ... > -...@end titlepage > - > -...@c So the toc is printed at the start. > -...@contents > - > -...@ifnottex > -...@node Top > -...@top LTTng Userspace Tracer > - > -This manual is for UST 0.5. > -...@end ifnottex > - > -...@menu > -* Overview:: > -* Installation:: > -* Quick start:: > -* Instrumenting an application:: > -* Recording a trace:: > -* Viewing traces:: > -* Performance:: > -* Resource Usage:: > -* List of environment variables detected by libust:: > -* GDB integration:: > -...@c * Copying:: Your rights and freedoms. > -...@end menu > - > -...@node Overview > -...@chapter Overview > - > -...@menu > -* What is UST?:: > -* License:: > -* Supported platforms:: > -...@end menu > - > -...@node What is UST? > -...@section What is UST? > - > -The LTTng Userspace Tracer (UST) is a library accompanied by a set of tools > to > -trace userspace code. > - > -Code may be instrumented with either markers or tracepoints. A highly > efficient > -lockless tracer records these events to a trace buffers. These buffers are > reaped > -by a deamon which writes trace data to disk. > - > -High performance is achieved by the use of lockless buffering algorithms, > RCU and > -per-cpu buffers. In addition, special care is taken to minize cache impact. > - > -...@node License > -...@section License > -The LTTng Userspace Tracer is intended to be linkable to open source software > -as well as to proprietary applications. This was accomplished by licensing > -the code that needs to be linked to the traced program as @acronym{LGPL}. > - > -Components licensed as LGPL v2.1: > -...@itemize @bullet > -...@item libust > -...@item libinterfork > -...@item libustcomm > -...@end itemize > - > -Components licensed as GPL v2: > -...@itemize @bullet > -...@item ustctl > -...@item libustcmd > -...@item ustd > -...@end itemize > - > -...@node Supported platforms > -...@section Supported platforms > - > -UST can currently trace applications running on Linux, on the x86-32, x86-64 > -and PowerPC 32 architectures. > - > -...@node Installation > -...@chapter Installation > - > -The LTTng userspace tracer is a library and a set of userspace tools. > - > -The following packages are required: > - > -...@itemize @bullet > -...@item > -ust > - > -This contains the tracing library, the ustd daemon, trace control tools > -and other helper tools. > - > -Repository: @url{http://git.dorsal.polymtl.ca} > - > -...@item > -liburcu > - > -This is the userspace read-copy update library by Mathieu Desnoyers. > - > -Available in Debian as package liburcu-dev. > - > -Home page: @url{http://lttng.org/urcu} > - > -...@item > -LTTV > - > -LTTV is a graphical (and text) viewer for LTTng traces. > - > -Home page: @url{http://lttng.org} > - > -...@end itemize > - > -Liburcu should be installed first. UST may then be compiled and installed. > LTTV > -has no dependency on the other packages; it may therefore be installed on a > -system which does not have UST installed. > - > -Refer to the README in each of these packages for installation instructions. > - > -...@c @menu > -...@c @end menu > - > -...@node Quick start > -...@chapter Quick start > - > -First, instrument a program with a marker. > - > -...@example > -...@verbatim > - > -#include <ust/marker.h> > - > -int main(int argc, char **argv) > -{ > - int v; > - char *st; > - > - /* ... set values of v and st ... */ > - > - /* a marker: */ > - trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st); > - > - /* a marker without arguments: */ > - trace_mark(ust, myotherevent, MARK_NOARGS); > - > - return 0; > -} > - > -...@end verbatim > -...@end example > - > -Then compile it in the regular way, linking it with libust. For example: > - > -...@example > -gcc -o foo -lust foo.c > -...@end example > - > -Run the program with @command{usttrace}. The @command{usttrace} output says > where the trace > -was written. > - > -...@example > -usttrace ./foo > -...@end example > - > -Finally, open the trace in LTTV. > - > -...@example > -lttv-gui -t /path/to/trace > -...@end example > - > -The trace can also be dumped as text in the console: > - > -...@example > -lttv -m textDump -t /path/to/trace > -...@end example > - > -...@node Instrumenting an application > -...@chapter Instrumenting an application > - > -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. > - > -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. > - > -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. > - > -In addition to executable programs, shared libraries may also be instrumented > -with the methods described in this chapter. > - > -...@menu > -* Markers:: > -* Tracepoints:: > -...@end menu > - > -...@node Markers > -...@section Markers > - > -Adding a marker is simply a matter of inserting one line in the program. > - > -...@example > -...@verbatim > -#include <ust/marker.h> > - > -int main(int argc, char **argv) > -{ > - int v; > - char *st; > - > - /* ... set values of v and st ... */ > - > - /* a marker: */ > - trace_mark(main, myevent, "firstarg %d secondarg %s", v, st); > - > - /* another marker without arguments: */ > - trace_mark(main, myotherevent, MARK_NOARGS); > - > - return 0; > -} > -...@end verbatim > -...@end example > - > -The invocation of the trace_mark() macro requires at least 3 arguments. The > -first, here "main", is the name of the event category. It is also the name of > -the channel the event will go in. The second, here "myevent" 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. > - > -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. > - > -...@node Tracepoints > -...@section Tracepoints > - > -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. > - > -...@quotation Note > -Although this example uses @emph{mychannel} as the channel, the > -only channel name currently supported with early tracing is @strong{ust}. The > -...@command{usttrace} tool always uses the early tracing mode. When using > manual > -mode without early tracing, any channel name may be used. > -...@end quotation > - > -A function instrumented with a tracepoint looks like this: > - > -...@example > -...@verbatim > -#include "tp.h" > - > -void function() > -{ > - int v; > - char *st; > - > - /* ... set values of v and st ... */ > - > - /* a tracepoint: */ > - trace_mychannel_myevent(v, st); > -} > -...@end verbatim > -...@end example > - > -Another file, here tp.h, contains declarations for the tracepoint. > - > -...@example > -...@verbatim > -#include <ust/tracepoint.h> > - > -DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st), > - TP_ARGS(v, st)); > -...@end verbatim > -...@end example > - > -A third file, here tp.c, contains definitions for the tracepoint. > - > -...@example > -...@verbatim > -#include <ust/marker.h> > -#include "tp.h" > - > -DEFINE_TRACE(mychannel_myevent); > - > -void mychannel_myevent_probe(int v, char *st) > -{ > - trace_mark(mychannel, myevent, "v %d st %s", v, st); > -} > - > -static void __attribute__((constructor)) init() > -{ > - register_trace_mychannel_myevent(mychannel_myevent_probe); > -} > -...@end verbatim > -...@end example > - > -Here, tp.h and tp.c could contain declarations and definitions for other > -tracepoints. The constructor would contain other register_* calls. > - > -...@node Recording a trace > -...@chapter Recording a trace > - > -...@menu > -* Using @command{usttrace}:: > -* Setting up the recording manually:: > -* Using early tracing:: > -* Crash recovery:: > -* Tracing across @code{fork()} and @code{clone()}:: > -* Tracing programs and libraries that were not linked to libust:: > -...@end menu > - > -...@node Using @command{usttrace} > -...@section Using @command{usttrace} > - > -The simplest way to record a trace is to use the @command{usttrace} script. > An > -example is given in the quickstart above. > - > -The @command{usttrace} script automatically: > -...@itemize @bullet > -...@item creates a daemon > -...@item enables all markers > -...@item runs the command specified on the command line > -...@item after the command ends, prints the location where the trace was > saved > -...@end itemize > - > -Each subdirectory of the save location contains the trace of one process that > -was generated by the command. The name of a subdirectory consists in the the > PID > -of the process, followed by the timestamp of its creation. > - > -The save location also contains logs of the tracing. > - > -When using @command{usttrace}, the early tracing is always active, which > means > -that the tracing is guaranteed to be started by the time the process enters > its > -...@code{main()} function. > - > -Several @command{usttrace}'s may be run simultaneously without risk of > -conflict. This facilitates the use of the tracer by idependent users on a > -system. Each instance of @command{usttrace} starts its own daemon which > -collects the events of the processes it creates. > - > -...@node Setting up the recording manually > -...@section Setting up the recording manually > - > -Instead of using @command{usttrace}, a trace may be recorded on an already > -running process. > - > -First the daemon must be started. > - > -...@example > -...@verbatim > -# Make sure the directory for the communication sockets exists. > -$ mkdir /tmp/ustsocks > - > -# Make sure the directory where ustd will write the trace exists. > -$ mkdir /tmp/trace > - > -# Start the daemon > -$ ustd > - > -# We assume the program we want to trace is already running and that > -# it has pid 1234. > - > -# List the available markers > -$ ustctl --list-markers 1234 > -# A column indicates 0 for an inactive marker and 1 for an active marker. > - > -# Enable a marker > -$ ustctl --enable-marker ust/mymark 1234 > - > -# Create a trace > -$ ustctl --create-trace 1234 > - > -# Start tracing > -$ ustctl --start-trace 1234 > - > -# Do things... > - > -# Stop tracing > -$ ustctl --stop-trace 1234 > - > -# Destroy the trace > -$ ustctl --destroy-trace 1234 > -...@end verbatim > -...@end example > - > -For more information about the manual mode, see the ustctl(1) man page. > - > -...@node Using early tracing > -...@section Using early tracing > - > -Early tracing consists in starting the tracing as early as possible in the > -program, so no events are lost between program start and the point where the > -command to start the tracing is given. When using early tracing, it is > -guaranteed that by the time the traced program enters its @code{main()} > -function, the tracing will be started. > - > -When using @command{usttrace}, the early tracing is always active. > - > -When using the manual mode (@command{ustctl}), early tracing is enabled using > -environment variables. Setting @env{UST_TRACE} to @code{1}, enables early > -tracing, while setting @env{UST_AUTOPROBE} to @code{1} enables all markers > -automatically. > - > - > -...@node Crash recovery > -...@section Crash recovery > - > -When a process being traced crashes, the daemon is able to recover all the > -events in its buffers that were successfully commited. This is possible > because > -the buffers are in a shared memory segment which remains available to the > -daemon even after the termination of the traced process. > - > -...@node Tracing across @code{fork()} and @code{clone()} > -...@section Tracing across @code{fork()} and @code{clone()} > - > -Tracing across @code{clone()} when the @code{CLONE_VM} flag is specified is > -supported without any particular action. > - > -When @code{clone()} is called without @code{CLONE_VM} or @code{fork()} is > -called, a new address space is created and the tracer must be notified to > -create new buffers for it. > - > -This can be done automatically, by @env{LD_PRELOAD}'ing > @file{libinterfork.so}. > -This library intercepts calls to @code{fork()} and informs the tracer it is > -being called. When using @command{usttrace}, this is accomplied by specifying > -the @option{-f} command line argument. > - > -Alternatively, the program can call @code{ust_before_fork()} before calling > -...@code{fork()} or @code{clone()} with @code{CLONE_VM}. After the call, > -...@code{ust_after_fork_parent()} must be called in the parent process and > -...@code{ust_after_fork_child()} must be called in the child process. > - > - > -...@node Tracing programs and libraries that were not linked to libust > -...@section Tracing programs and libraries that were not linked to libust > - > -Some programs need to be traced even though they were not linked to libust > -either because they were not instrumented or because it was not practical. > - > -An executable that is not instrumented can still yield interesting traces > when > -at least one of its dynamic libraries is instrumented. It is also possible to > -trace certain function calls by intercepting them with a specially crafted > -library that is linked with @env{LD_PRELOAD} at program start. > - > -In any case, a program that was not linked to libust at compile time must be > -linked to it at run time with @env{LD_PRELOAD}. This can be accomplished with > -...@command{usttrace}'s @option{-l} option. It can also be done by setting > the > -...@env{ld_preload} environment variable on the command line. For example: > - > -...@example > -...@verbatim > -# Run ls with usttrace, LD_PRELOAD'ing libust > -# (assuming one of the libraries used by ls is instrumented). > -$ usttrace -l ls > - > -# Run ls, manually adding the LD_PRELOAD. > -$ LD_PRELOAD=/usr/local/lib/libust.so.0 ls > -...@end verbatim > -...@end example > - > - > -...@node Performance > -...@chapter Performance > - > -Todo. > - > -...@node Viewing traces > -...@chapter Viewing traces > - > -Traces may be viewed with LTTV. An example of command for launching LTTV is > -given in the quickstart. > - > -...@menu > -* Viewing multiple traces:: > -* Combined kernel-userspace tracing:: > -...@end menu > - > -...@node Viewing multiple traces > -...@section Viewing multiple traces > - > -When tracing multi-process applications or several applications > simultaneously, > -more than one trace will be obtained. LTTV can open and display all these > -traces simultaneously. > - > -...@node Combined kernel-userspace tracing > -...@section Combined kernel-userspace tracing > - > -In addition to multiple userspace traces, LTTV can open a kernel trace > recorded > -with the LTTng kernel tracer. This provides events that enable the rendering > of > -the Control Flow View and the Resource View. > - > -When doing so, it is necessary to use the same time source for the kernel > -tracer as well as the userspace tracer. Currently, the recommended method is > to > -use the timestamp counter for both. The TSC can however only be used on > architectures > -where it is synchronized across cores. > - > -...@node Resource Usage > -...@chapter Resource Usage > - > -The purpose of this section is to give an overview of the resource usage of > libust. For > -a developer, knowing this can be important: because libust is linked with > applications, it > -needs to share some resources with it. Some applications may make some > assumptions that are in > -conflict with libust's usage of resources. > - > -In practice however, libust is designed to be transparent and is compatible > -with the vast majority of applications. This means no changes are required in > -the application (or library) being linked to libust. > - > -Libust is initialized by a constructor, which by definition runs before the > -...@code{main()} function of the application starts. This constructor > creates a > -thread called the @emph{listener thread}. The listener thread initializes a > -named socket and waits for connections for ustd or ustctl. > - > -Libust-specific code may: > -...@itemize @bullet > -...@item use @code{malloc()} and @code{free()} > -...@item map shared memory segment in the process adress space > -...@item intercept some library calls, specifically @code{fork()} and > @code{clone()} > -...@item do interprocess communication with the daemon or ustctl > -...@item create and open named sockets > - > -...@end itemize > - > -It will not: > -...@itemize @bullet > -...@item handle any signal (all signals are blocked in the listener thread) > -...@item change any process-wide setting that could confuse the application > -...@end itemize > - > -...@node List of environment variables detected by libust > -...@appendix List of environment variables detected by libust > - > -The behavior of tracing can be influenced by setting special environment > -variables in the environment of the traced application. This section > -describes these variables. > - > -...@itemize @bullet > - > -...@item > -...@env{ust_trace} > - > -If set to 1, start tracing as soon as the program starts. Tracing is > -guaranteed to be started by the time the @code{main()} function starts. > - > -...@item > -...@env{ust_autoprobe} > - > -If set to @code{1}, enable all markers by the time the @code{main()} > function starts. > - > -...@item > -...@env{ust_autocollect} > - > -If set to @code{0}, disable notification of daemon on trace start. Useful for > -performance tests. > - > -...@item > -...@env{ust_overwrite} > - > -If set to @code{1}, enable overwriting of buffers on overrun. > - > -...@item > -...@env{ust_subbuf_num} > - > -If set, defines the default number of subbuffers per buffer. > - > -...@item > -...@env{ust_subbuf_size} > - > -If set, defines the default size of subbuffers, in bytes. > - > -...@end itemize > - > -...@node GDB integration > -...@appendix GDB integration > - > -GDB, the GNU Debugger, can use UST markers as GDB tracepoints (note GDB has > its > -own concept of tracepoint). This feature is called GDB Static Tracepoints. > When > -a GDB tracepoint is hit, GDB collects the marker arguments, as well as the > -state of the registers. > - > -In UST, support for GDB integration is not compiled in by default because of > -the cost of saving registers when a marker is hit. To enable it, run the > -...@command{./configure} script with the @code{-DCONFIG_UST_GDB_INTEGRATION} > flag > -in the @env{CFLAGS} environment variable. For example: > - > -...@example > -...@verbatim > - > -CFLAGS=-DCONFIG_UST_GDB_INTEGRATION ./configure > - > -...@end verbatim > -...@end example > - > -As of this writing, GDB Static Tracepoints have been submitted > -(@url{http://sourceware.org/ml/gdb-patches/2010-06/msg00592.html}) to the GDB > -mailing list. > - > -GDB integration is currently only supported on x86-32 and x86-64. > - > -...@bye > -- > 1.7.1 > > > _______________________________________________ > ltt-dev mailing list > [email protected] > http://lists.casi.polymtl.ca/cgi-bin/mailman/listinfo/ltt-dev > -- Mathieu Desnoyers Operating System Efficiency R&D Consultant EfficiOS Inc. http://www.efficios.com _______________________________________________ ltt-dev mailing list [email protected] http://lists.casi.polymtl.ca/cgi-bin/mailman/listinfo/ltt-dev
