ACLOCAL_AMFLAGS = -I config
-SUBDIRS = . include doc snprintf libringbuffer liblttng-ust-comm \
+SUBDIRS = . include snprintf libringbuffer liblttng-ust-comm \
liblttng-ust \
liblttng-ust-ctl \
liblttng-ust-fork \
Makefile
include/Makefile
include/lttng/ust-version.h
- doc/Makefile
- doc/man/Makefile
- doc/info/Makefile
snprintf/Makefile
libringbuffer/Makefile
liblttng-ust-comm/Makefile
+++ /dev/null
-SUBDIRS = man info
+++ /dev/null
-EXTRA_DIST = ust.texi
-info_TEXINFOS = ust.texi
+++ /dev/null
-\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
+++ /dev/null
-EXTRA_DIST = ustctl.1 ust-consumerd.1 usttrace.1
-man_MANS = ustctl.1 ust-consumerd.1 usttrace.1
+++ /dev/null
-.\" generated with Ronn/v0.5
-.\" http://github.com/rtomayko/ronn/
-.
-.TH "UST-CONSUMERD" "1" "May 2010" "" ""
-.
-.SH "NAME"
-\fBust-consumerd\fR \-\- a daemon that collects trace data and writes it to the disk
-.
-.SH "SYNOPSIS"
-\fBust-consumerd\fR [\fIoptions\fR]
-.
-.SH "DESCRIPTION"
-\fBust-consumerd\fR is a program that collects trace data and writes it to the disk.
-.
-.SH "OPTIONS"
-These programs follow the usual GNU command line syntax, with long options
-starting with two dashes(`\-'). A summary of options is included below.
-.
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-Show summary of options.
-.
-.TP
-\fB\-o\fR \fIDIR\fR
-Specify the directory where to output the traces.
-.
-.TP
-\fB\-s\fR \fIPATH\fR
-Specify the path to use for the daemon socket.
-.
-.TP
-\fB\-d\fR
-Start as a daemon.
-.
-.TP
-\fB\-p\fR, \fB\-\-pidfile\fR=\fIFILE\fR
-Write the PID in this file (when using \-d).
-.
-.TP
-\fB\-V\fR, \fB\-\-version\fR
-Show version of program.
-.
-.SH "SEE ALSO"
-ustctl(1), usttrace(1)
-.
-.SH "AUTHOR"
-\fBust-consumerd\fR was written by Pierre\-Marc Fournier.
-.
-.P
-This manual page was written by Jon Bernard <jbernard@debian.org>, for
-the Debian project (and may be used by others).
+++ /dev/null
-ust-consumerd(1) -- a daemon that collects trace data and writes it to the disk
-======================================================================
-
-## SYNOPSIS
-
-`ust-consumerd` [<options>]
-
-## DESCRIPTION
-
-`ust-consumerd` is a program that collects trace data and writes it to the disk.
-
-## OPTIONS
-
-These programs follow the usual GNU command line syntax, with long options
-starting with two dashes(`-'). A summary of options is included below.
-
- * `-h`, `--help`:
- Show summary of options.
-
- * `-o` <DIR>:
- Specify the directory where to output the traces.
-
- * `-s` <PATH>:
- Specify the path to use for the daemon socket.
-
- * `-d`:
- Start as a daemon.
-
- * `-p`, `--pidfile`=<FILE>:
- Write the PID in this file (when using -d).
-
- * `-V`, `--version`:
- Show version of program.
-
-## SEE ALSO
-
-ustctl(1), usttrace(1)
-
-## AUTHOR
-
-`ust-consumerd` was written by Pierre-Marc Fournier.
-
-This manual page was written by Jon Bernard <jbernard@debian.org>, for
-the Debian project (and may be used by others).
+++ /dev/null
-.\" generated with Ronn/v0.7.3
-.\" http://github.com/rtomayko/ronn/tree/0.7.3
-.
-.TH "USTCTL" "1" "January 2011" "" ""
-.
-.SH "NAME"
-\fBustctl\fR \- a program to control the tracing of userspace applications
-.
-.SH "SYNOPSIS"
-\fBustctl\fR [\fICOMMAND\fR] [\fIARGS\fR]\.\.\.
-.
-.SH "DESCRIPTION"
-\fBustctl\fR is a program to control the tracing of userspace applications\. It can list markers, start the tracing, stop the tracing, enable/disable markers, etc\.
-.
-.SH "OPTIONS"
-These programs follow the usual GNU command line syntax, with long options starting with two dashes(`\-\')\. A summary of options is included below\.
-.
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-Show summary of commands\.
-.
-.SH "COMMANDS"
-\fBustctl\fR accepts commands followed by arguments for each respective command\. Most commands require the pid of the application being traced\.
-.
-.TP
-\fBcreate\-trace\fR \fIPID\fR \fITRACE\fR
-Create trace\.
-.
-.TP
-\fBalloc\-trace\fR \fIPID\fR \fITRACE\fR
-Allocate trace\.
-.
-.TP
-\fBstart\-trace\fR \fIPID\fR \fITRACE\fR
-Start tracing\.
-.
-.TP
-\fBstop\-trace\fR \fIPID\fR \fITRACE\fR
-Stop tracing\.
-.
-.TP
-\fBdestroy\-trace\fR \fIPID\fR \fITRACE\fR
-Destroy the trace\.
-.
-.TP
-\fBset\-subbuf\-size\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fIbytes\fR
-Set the size of subbuffers in CHANNEL\.
-.
-.TP
-\fBset\-subbuf\-num\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fInr\fR
-Set the number of subbuffers per buffer for CHANNEL\. Must be a power of 2\.
-.
-.TP
-\fBset\-sock\-path\fR \fIPID\fR \fISOCKPATH\fR
-Set the path of the daemon socket\.
-.
-.TP
-\fBget\-subbuf\-size\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR
-Print the size of subbuffers per buffer for CHANNEL\.
-.
-.TP
-\fBget\-subbuf\-num\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR
-Print the number of subbuffers per buffer for CHANNEL\.
-.
-.TP
-\fBget\-sock\-path\fR \fIPID\fR
-Get the path of the daemon socket\.
-.
-.TP
-\fBenable\-marker\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fIMARKER\fR
-Enable a marker\.
-.
-.TP
-\fBdisable\-marker\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fIMARKER\fR
-Disable a marker\.
-.
-.TP
-\fBlist\-markers\fR \fIPID\fR
-List the markers of the process, their state and format string\.
-.
-.TP
-\fBforce\-subbuf\-switch\fR \fIPID\fR \fITRACE\fR
-Force a subbuffer switch\. This will flush all the data currently held\.
-.
-.SH "LIFE CYCLE OF A TRACE"
-Typically, the first step is to enable markers with \fBenable\-marker\fR\. An enabled marker generates an event when the control flow passes over it (assuming the trace is recording)\. A disabled marker produces nothing\. Enabling and disabling markers may however be done at any point, including while the trace is being recorded\.
-.
-.P
-In order to record events, a trace is first created with \fBcreate\-trace\fR\. At this point, the subbuffer count and size may be changed with \fBset\-subbuf\-num\fR and \fBset\-subbuf\-size\fR\.
-.
-.P
-Afterward, the trace may be allocated with \fBalloc\-trace\fR\. This allocates the buffers in memory, so once this is done, the subbuffer size and count can not be changed\. Trace allocation also causes the daemon to connect to the trace buffers and wait for data to arrive\. Explicit allocation is optional, as it is done automatically at trace start\.
-.
-.P
-The trace may then be started with \fBstart\-trace\fR\. This results in events being recorded in the buffer\. The daemon automatically collects these events\.
-.
-.P
-The trace may be stopped with \fBstop\-trace\fR, either definitely after all the wanted information is collected, or temporarily, before being started again with \fBstart\-trace\fR\. This results in effectively \'pausing\' the recording\. After using \fBstop\-trace\fR, if a daemon is collecting the trace, it may not have flushed to the disk the full contents of the buffer yet\.
-.
-.P
-Finally, when \fBdestroy\-trace\fR is used, the trace buffers are unallocated\. However, the memory may not be effectively freed until the daemon finishes to collect them\. When the trace is being collected by \fBust\-consumerd\fR, this command guarantees its full contents is flushed to the disk\.
-.
-.SH "STRUCTURE OF A TRACE"
-Each instrumentation point that is added in a program is associated to a channel\.
-.
-.P
-Trace events are put in buffers\. There is one buffer per channel, per cpu\. For example, on a system with 4 cores and tracing an application with 3 channels, there will be 12 buffers in total\. The content of each of these buffers is put in a distinct file in the trace directory\. For example, the \fBmetadata_2\fR file contains the data that was extracted from the buffer that contained the events from the metadata channel and having occurred on cpu 2\.
-.
-.P
-In memory, each buffer is divided in subbuffers\. Subbuffers are equally\-sized, contiguous parts of a buffer\. The size of a buffer is equal to the number of subbuffers it contains times the size of each subbuffer\. When a subbuffer is full, it is collected by the daemon while the others are filled\. If, however, the buffer size is too small, buffer overflows may occur and result in event loss\. By default, the number of subbuffers per buffer is 2\. Subbuffer size for a given channel may be chosen with \fBset\-subbuf\-size\fR while the subbuffer count is set with \fBset\-subbuf\-num\fR\.
-.
-.SH "SEE ALSO"
-usttrace(1), ust\-consumerd(1)
-.
-.SH "AUTHOR"
-\fBustctl\fR was written by Pierre\-Marc Fournier\.
-.
-.P
-This manual page was written by Jon Bernard <jbernard@debian\.org>, for the Debian project (and may be used by others)\. It was updated by Pierre\-Marc Fournier\.
+++ /dev/null
-ustctl(1) -- a program to control the tracing of userspace applications
-=======================================================================
-
-## SYNOPSIS
-
-`ustctl` [<COMMAND>] [<ARGS>]...
-
-## DESCRIPTION
-
-`ustctl` is a program to control the tracing of userspace applications. It can
-list markers, start the tracing, stop the tracing, enable/disable markers, etc.
-
-## OPTIONS
-
-These programs follow the usual GNU command line syntax, with long options
-starting with two dashes(`-'). A summary of options is included below.
-
- * `-h`, `--help`:
- Show summary of commands.
-
-## COMMANDS
-
-`ustctl` accepts commands followed by arguments for each respective command.
-Most commands require the pid of the application being traced.
-
- * `create-trace` <PID> <TRACE>:
- Create trace.
-
- * `alloc-trace` <PID> <TRACE>:
- Allocate trace.
-
- * `start-trace` <PID> <TRACE>:
- Start tracing.
-
- * `stop-trace` <PID> <TRACE>:
- Stop tracing.
-
- * `destroy-trace` <PID> <TRACE>:
- Destroy the trace.
-
- * `set-subbuf-size` <PID> <TRACE> <CHANNEL>/<bytes>:
- Set the size of subbuffers in CHANNEL.
-
- * `set-subbuf-num` <PID> <TRACE> <CHANNEL>/<nr>:
- Set the number of subbuffers per buffer for CHANNEL. Must be a power of 2.
-
- * `set-sock-path` <PID> <SOCKPATH>:
- Set the path of the daemon socket.
-
- * `get-subbuf-size` <PID> <TRACE> <CHANNEL>:
- Print the size of subbuffers per buffer for CHANNEL.
-
- * `get-subbuf-num` <PID> <TRACE> <CHANNEL>:
- Print the number of subbuffers per buffer for CHANNEL.
-
- * `get-sock-path` <PID>:
- Get the path of the daemon socket.
-
- * `enable-marker` <PID> <TRACE> <CHANNEL>/<MARKER>:
- Enable a marker.
-
- * `disable-marker` <PID> <TRACE> <CHANNEL>/<MARKER>:
- Disable a marker.
-
- * `list-markers` <PID>:
- List the markers of the process, their state and format string.
-
- * `force-subbuf-switch` <PID> <TRACE>:
- Force a subbuffer switch. This will flush all the data currently held.
-
-## LIFE CYCLE OF A TRACE
-
-Typically, the first step is to enable markers with `enable-marker`. An
-enabled marker generates an event when the control flow passes over it
-(assuming the trace is recording). A disabled marker produces nothing. Enabling
-and disabling markers may however be done at any point, including while the
-trace is being recorded.
-
-In order to record events, a trace is first created with `create-trace`. At
-this point, the subbuffer count and size may be changed with `set-subbuf-num`
-and `set-subbuf-size`.
-
-Afterward, the trace may be allocated with `alloc-trace`. This allocates the
-buffers in memory, so once this is done, the subbuffer size and count can not
-be changed. Trace allocation also causes the daemon to connect to the trace
-buffers and wait for data to arrive. Explicit allocation is optional, as it is
-done automatically at trace start.
-
-The trace may then be started with `start-trace`. This results in events
-being recorded in the buffer. The daemon automatically collects these events.
-
-The trace may be stopped with `stop-trace`, either definitely after all the
-wanted information is collected, or temporarily, before being started again
-with `start-trace`. This results in effectively 'pausing' the recording.
-After using `stop-trace`, if a daemon is collecting the trace, it may not
-have flushed to the disk the full contents of the buffer yet.
-
-Finally, when `destroy-trace` is used, the trace buffers are unallocated.
-However, the memory may not be effectively freed until the daemon finishes to
-collect them. When the trace is being collected by `ust-consumerd`, this command
-guarantees its full contents is flushed to the disk.
-
-## STRUCTURE OF A TRACE
-
-Each instrumentation point that is added in a program is associated to a
-channel.
-
-Trace events are put in buffers. There is one buffer per channel, per cpu.
-For example, on a system with 4 cores and tracing an application with 3
-channels, there will be 12 buffers in total. The content of each of these
-buffers is put in a distinct file in the trace directory. For example, the
-`metadata_2` file contains the data that was extracted from the buffer that
-contained the events from the metadata channel and having occurred on cpu 2.
-
-In memory, each buffer is divided in subbuffers. Subbuffers are equally-sized,
-contiguous parts of a buffer. The size of a buffer is equal to the number of
-subbuffers it contains times the size of each subbuffer. When a subbuffer is
-full, it is collected by the daemon while the others are filled. If, however,
-the buffer size is too small, buffer overflows may occur and result in event
-loss. By default, the number of subbuffers per buffer is 2. Subbuffer size
-for a given channel may be chosen with `set-subbuf-size` while the subbuffer
-count is set with `set-subbuf-num`.
-
-## SEE ALSO
-
-usttrace(1), ust-consumerd(1)
-
-## AUTHOR
-
-`ustctl` was written by Pierre-Marc Fournier.
-
-This manual page was written by Jon Bernard <jbernard@debian.org>, for
-the Debian project (and may be used by others). It was updated by Pierre-Marc
-Fournier.
+++ /dev/null
-.\" generated with Ronn/v0.5
-.\" http://github.com/rtomayko/ronn/
-.
-.TH "USTTRACE" "1" "May 2010" "" ""
-.
-.SH "NAME"
-\fBusttrace\fR \-\- the simplest way to record a trace
-.
-.SH "SYNOPSIS"
-\fBusttrace\fR [\fIoptions\fR] [\fIcommand\fR]
-.
-.SH "DESCRIPTION"
-The \fBusttrace\fR script automatically:
-.
-.IP "\(bu" 4
-creates a daemon
-.
-.IP "\(bu" 4
-enables all markers
-.
-.IP "\(bu" 4
-runs the command specified on the command line
-.
-.IP "\(bu" 4
-after the command ends, prints the location where the trace was saved
-.
-.IP "" 0
-.
-.P
-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 PID of
-the process, followed by the timestamp of its creation.
-.
-.P
-The save location also contains logs of the tracing.
-.
-.P
-When using 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.
-.
-.P
-Several usttrace's may be run simultaneously without risk of conflict. This
-facilitates the use of the tracer by independent users on a system. Each
-instance of usttrace starts its own daemon which collects the events of the
-processes it creates.
-.
-.SH "OPTIONS"
-These programs follow the usual GNU command line syntax, with long options
-starting with two dashes(`\-'). A summary of options is included below.
-.
-.TP
-\fB\-h\fR
-Show summary of options.
-.
-.TP
-\fB\-o\fR
-Set the trace output directory
-.
-.TP
-\fB\-l\fR
-Runtime link with UST library. (Needed only if program was not linked at
-compile time with libust.)
-.
-.TP
-\fB\-L\fR
-Add path to ust libraries to LD_LIBRARY_PATH.
-.
-.TP
-\fB\-m\fR
-Instrument malloc calls.
-.
-.TP
-\fB\-f\fR
-Also trace forked processes.
-.
-.TP
-\fB\-s\fR
-Use system\-wide daemon instead of creating one for this session.
-.
-.TP
-\fB\-S\fR
-Specify the subbuffer size.
-.
-.TP
-\fB\-N\fR
-Specify the number of subbuffers.
-.
-.TP
-\fB\-W\fR
-Print the location of the last trace saved in the usttrace output directory.
-.
-.SH "SEE ALSO"
-ustctl(1), ust-consumerd(1)
-.
-.SH "AUTHOR"
-\fBusttrace\fR was written by Pierre\-Marc Fournier.
-.
-.P
-This manual page was written by Jon Bernard <jbernard@debian.org>, for
-the Debian project (and may be used by others).
+++ /dev/null
-usttrace(1) -- the simplest way to record a trace
-=================================================
-
-## SYNOPSIS
-
-`usttrace` [<options>] [<command>]
-
-## DESCRIPTION
-
-The `usttrace` script automatically:
-
-* creates a daemon
-* enables all markers
-* runs the command specified on the command line
-* after the command ends, prints the location where the trace was saved
-
-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 PID of
-the process, followed by the timestamp of its creation.
-
-The save location also contains logs of the tracing.
-
-When using 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.
-
-Several usttrace's may be run simultaneously without risk of conflict. This
-facilitates the use of the tracer by independent users on a system. Each
-instance of usttrace starts its own daemon which collects the events of the
-processes it creates.
-
-## OPTIONS
-
-These programs follow the usual GNU command line syntax, with long options
-starting with two dashes(`-'). A summary of options is included below.
-
- * `-h`:
- Show summary of options.
-
- * `-l`:
- Runtime link with UST library. (Needed only if program was not linked at
- compile time with libust.)
-
- * `-L`:
- Add path to ust libraries to LD_LIBRARY_PATH.
-
- * `-m`:
- Instrument malloc calls.
-
- * `-f`:
- Also trace forked processes.
-
- * `-s`:
- Use system-wide daemon instead of creating one for this session.
-
- * `-S`:
- Specify the subbuffer size.
-
- * `-N`:
- Specify the number of subbuffers.
-
- * `-W`:
- Print the location of the last trace saved in the usttrace output directory.
-
-## SEE ALSO
-
-ustctl(1), ust-consumerd(1)
-
-
-## AUTHOR
-
-`usttrace` was written by Pierre-Marc Fournier.
-
-This manual page was written by Jon Bernard <jbernard@debian.org>, for
-the Debian project (and may be used by others).
projects / lttng-ust.git / commitdiff
