X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fmanual%2Fmanual.texinfo;h=ad8ebe904cd6b40e735847e5928eb0481c2aaa4b;hb=72d022d60207b479177401cfdeddeb685d5aa85f;hp=b0b588df40c4af96bca668c50618415b01443f65;hpb=5cd1099a9a3210708ae6f3951cd4a26a68028e6b;p=ust.git diff --git a/doc/manual/manual.texinfo b/doc/manual/manual.texinfo index b0b588d..ad8ebe9 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.4. @end ifnottex @menu @@ -47,6 +47,7 @@ This manual is for UST 0.1. * Recording a trace:: * Viewing traces:: * Performance:: +* Resource Usage:: @c * Copying:: Your rights and freedoms. @end menu @@ -54,13 +55,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 +113,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 +122,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 +224,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 +240,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 +268,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 +300,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 @@ -365,7 +397,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 @@ -377,9 +409,14 @@ $ ustctl --start-trace 1234 # 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 @@ -408,23 +445,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 @@ -434,4 +499,64 @@ 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 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 + + @bye