X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fmanual%2Fmanual.texinfo;h=385cb35a18e7c3d4808a9314cf70a7c71c244dca;hb=c3947c2532de17dc257f17e819501e02369f49b6;hp=b0b588df40c4af96bca668c50618415b01443f65;hpb=5cd1099a9a3210708ae6f3951cd4a26a68028e6b;p=ust.git diff --git a/doc/manual/manual.texinfo b/doc/manual/manual.texinfo index b0b588d..385cb35 100644 --- a/doc/manual/manual.texinfo +++ b/doc/manual/manual.texinfo @@ -54,9 +54,44 @@ 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 @@ -194,7 +229,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 +245,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; @@ -268,8 +303,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 +400,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 +412,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 +448,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 +502,31 @@ 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. + @bye