Update info page for 0.14 API

[ust.git] / doc / info / ust.texi

\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.14.
@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 libustctl
@item ust-consumerd
@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 ust-consumerd daemon, trace control tools
and other helper tools.

Repository: @url{http://lttng.org/ust}

@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: */
        ust_marker(myevent, "firstarg %d secondarg %s", v, st);

        /* a marker without arguments: */
        ust_marker(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: */
        ust_marker(myevent, "firstarg %d secondarg %s", v, st);

        /* another marker without arguments: */
        ust_marker(myotherevent, MARK_NOARGS);

        return 0;
}
@end verbatim
@end example

The invocation of the ust_marker() macro requires at least 2 arguments. The
first, "myevent", is the name of the event. The second 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 Tracepoint API is superseded by TRACEPOINT_EVENT() (which uses the
Tracepoints internally). At this stage, TRACEPOINT_EVENT() is work in
progress. While we complete this API, please use the ust_marker() API
provided by ust/marker.h.

@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 ust-consumerd will write the trace exists.
$ mkdir /tmp/trace

# Start the daemon
$ ust-consumerd

# 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 1234 auto ust/mymark

# Create a trace
$ ustctl create-trace 1234 auto

# Start tracing
$ ustctl start-trace 1234 auto

# Do things...

# Stop tracing
$ ustctl stop-trace 1234 auto

# Destroy the trace
$ ustctl destroy-trace 1234 auto
@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 ust-consumerd 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. Support for GDB is currently work in progress.

@bye