-.\" generated with Ronn/v0.4.1
+.\" generated with Ronn/v0.5
.\" http://github.com/rtomayko/ronn/
.
-.TH "USTCTL" "1" "March 2010" "" ""
+.TH "USTCTL" "1" "May 2010" "" ""
.
.SH "NAME"
\fBustctl\fR \-\- a program to control the tracing of userspace applications
\fBustctl\fR [\fIcommand\fR] [\fIPIDs\fR]...
.
.SH "DESCRIPTION"
-\fBustclt\fR is a program to control the tracing of userspace applications. It can
+\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"
.
.TP
\fB\-\-alloc\-trace\fR
-Alloc trace.
+Allocate trace.
.
.TP
\fB\-\-start\-trace\fR
.
.TP
\fB\-\-set\-subbuf\-size\fR \fICHANNEL\fR/\fIbytes\fR
-Set the size of subbuffers per channel.
+Set the size of subbuffers in CHANNEL.
.
.TP
\fB\-\-set\-subbuf\-num\fR \fICHANNEL\fR
-Set the number of subbuffers per channel.
+Set the number of subbuffers per buffer for CHANNEL. Must be a power of 2.
.
.TP
\fB\-\-get\-subbuf\-size\fR \fICHANNEL\fR
-Get the size of subbuffers per channel.
+Print the size of subbuffers per buffer for CHANNEL.
.
.TP
\fB\-\-get\-subbuf\-num\fR \fICHANNEL\fR
-Get the number of subbuffers per channel.
+Print the number of subbuffers per buffer for CHANNEL.
.
.TP
\fB\-\-enable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR
\fB\-\-list\-markers\fR
List the markers of the process, their state and format string.
.
+.SH "LIFE CYCLE OF A TRACE"
+Typically, the first step is to enable markers with \fB\-\-enable\-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 \fB\-\-create\-trace\fR. At
+this point, the subbuffer count and size may be changed with \fB\-\-set\-subbuf\-num\fR
+and \fB\-\-set\-subbuf\-size\fR.
+.
+.P
+Afterward, the trace may be allocated with \fB\-\-alloc\-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 \fB\-\-start\-trace\fR. This results in events
+being recorded in the buffer. The daemon automatically collects these events.
+.
+.P
+The trace may be stopped with \fB\-\-stop\-trace\fR, either definitely after all the
+wanted information is collected, or temporarily, before being started again
+with \fB\-\-start\-trace\fR. This results in effectively "pausing" the recording.
+.
+.P
+Finally, when \fB\-\-destroy\-trace\fR is used, the trace buffers are unallocated.
+However, the memory may not be effectively freed until the daemon finishes to
+collect them.
+.
+.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 \fB\-\-set\-subbuf\-size\fR while the subbuffer
+count is set with \fB\-\-set\-subbuf\-num\fR.
+.
+.SH "SEE ALSO"
+usttrace(1), ustd(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).
+the Debian project (and may be used by others). It was updated by Pierre\-Marc
+Fournier.
## DESCRIPTION
-`ustclt` is a program to control the tracing of userspace applications. It can
+`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
Create trace.
* `--alloc-trace`:
- Alloc trace.
+ Allocate trace.
* `--start-trace`:
Start tracing.
Destroy the trace.
* `--set-subbuf-size` <CHANNEL>/<bytes>:
- Set the size of subbuffers per channel.
+ Set the size of subbuffers in CHANNEL.
* `--set-subbuf-num` <CHANNEL>:
- Set the number of subbuffers per channel.
+ Set the number of subbuffers per buffer for CHANNEL. Must be a power of 2.
* `--get-subbuf-size` <CHANNEL>:
- Get the size of subbuffers per channel.
+ Print the size of subbuffers per buffer for CHANNEL.
* `--get-subbuf-num` <CHANNEL>:
- Get the number of subbuffers per channel.
+ Print the number of subbuffers per buffer for CHANNEL.
* `--enable-marker` <CHANNEL>/<MARKER>:
Enable a marker.
* `--list-markers`:
List the markers of the process, their state and format string.
+## 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.
+
+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.
+
+## 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), ustd(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).
+the Debian project (and may be used by others). It was updated by Pierre-Marc
+Fournier.
-.\" generated with Ronn/v0.4.1
+.\" generated with Ronn/v0.5
.\" http://github.com/rtomayko/ronn/
.
-.TH "USTD" "1" "March 2010" "" ""
+.TH "USTD" "1" "May 2010" "" ""
.
.SH "NAME"
\fBustd\fR \-\- a daemon that collects trace data and writes it to the disk
\fB\-V\fR, \fB\-\-version\fR
Show version of program.
.
+.SH "SEE ALSO"
+ustctl(1), usttrace(1)
+.
.SH "AUTHOR"
\fBustd\fR was written by Pierre\-Marc Fournier.
.
* `-V`, `--version`:
Show version of program.
+## SEE ALSO
+
+ustctl(1), usttrace(1)
+
## AUTHOR
`ustd` was written by Pierre-Marc Fournier.
\fB\-W\fR
Undocumented option.
.
+.SH "SEE ALSO"
+ustctl(1), ustd(1)
+.
.SH "AUTHOR"
\fBusttrace\fR was written by Pierre\-Marc Fournier.
.
* `-W`:
Undocumented option.
+## SEE ALSO
+
+ustctl(1), ustd(1)
+
+
## AUTHOR
`usttrace` was written by Pierre-Marc Fournier.
@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
projects / ust.git / commitdiff
