X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fmanual%2Fmanual.texinfo;h=e0565f39a96261c73e291fca68eeee6dd58760c9;hb=245d371ea1c17d6196af065a40dfcdc671b40f41;hp=941e76b25b662fbb031b64d38c1beaec401d87b8;hpb=1af1f1db733ce22be32ba7b253279097909a26e4;p=ust.git diff --git a/doc/manual/manual.texinfo b/doc/manual/manual.texinfo index 941e76b..e0565f3 100644 --- a/doc/manual/manual.texinfo +++ b/doc/manual/manual.texinfo @@ -36,7 +36,7 @@ Permission is granted to ... @node Top @top LTTng Userspace Tracer -This manual is for UST 0.1. +This manual is for UST 0.5. @end ifnottex @menu @@ -47,6 +47,9 @@ This manual is for UST 0.1. * 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 @@ -54,13 +57,49 @@ This manual is for UST 0.1. @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 and x86-64 architectures. +UST can currently trace applications running on Linux, on the x86-32, x86-64 +and PowerPC 32 architectures. @node Installation @chapter Installation @@ -76,14 +115,7 @@ ust This contains the tracing library, the ustd daemon, trace control tools and other helper tools. -Repository: http://git.dorsal.polymtl.ca - -@item -libkcompat - -This is a library that contains a userspace port of some kernel APIs. - -Repository: http://git.dorsal.polymtl.ca +Repository: @url{http://git.dorsal.polymtl.ca} @item liburcu @@ -92,20 +124,20 @@ This is the userspace read-copy update library by Mathieu Desnoyers. Available in Debian as package liburcu-dev. -Home page: http://lttng.org/?q=node/18 +Home page: @url{http://lttng.org/urcu} @item LTTV LTTV is a graphical (and text) viewer for LTTng traces. -Home page: http://lttng.org +Home page: @url{http://lttng.org} @end itemize -Libkcompat and 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. +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. @@ -194,7 +226,7 @@ with the methods described in this chapter. @node Markers @section Markers -Adding a marker is simply a matter of insert one line in the program. +Adding a marker is simply a matter of inserting one line in the program. @example @verbatim @@ -210,7 +242,7 @@ int main(int argc, char **argv) /* a marker: */ trace_mark(main, myevent, "firstarg %d secondarg %s", v, st); - /* a marker without arguments: */ + /* another marker without arguments: */ trace_mark(main, myotherevent, MARK_NOARGS); return 0; @@ -238,10 +270,12 @@ 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 +@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 +mode without early tracing, any channel name may be used. +@end quotation A function instrumented with a tracepoint looks like this: @@ -268,8 +302,8 @@ Another file, here tp.h, contains declarations for the tracepoint. @verbatim #include -DECLARE_TRACE(mychannel_myevent, TPPROTO(int v, char *st), - TPARGS(v, st)); +DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st), + TP_ARGS(v, st)); @end verbatim @end example @@ -331,7 +365,7 @@ 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 -main() function. +@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 @@ -365,7 +399,7 @@ $ ustctl --list-markers 1234 # A column indicates 0 for an inactive marker and 1 for an active marker. # Enable a marker -$ ustctl --enable-marker 1234 ust/mymark +$ ustctl --enable-marker ust/mymark 1234 # Create a trace $ ustctl --create-trace 1234 @@ -383,6 +417,8 @@ $ 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 @@ -411,23 +447,51 @@ 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 @code{CLONE_VM} is specified is supported -without any particular action. +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. @strong{TODO: specify how to do it.} +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. -This can be done automatically (for @code{fork()} only for now), 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. @node Tracing programs and libraries that were not linked to libust @section Tracing programs and libraries that were not linked to libust -Todo. +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 @@ -437,4 +501,134 @@ 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