From c3947c2532de17dc257f17e819501e02369f49b6 Mon Sep 17 00:00:00 2001 From: Pierre-Marc Fournier Date: Wed, 26 May 2010 18:32:59 -0400 Subject: [PATCH] documentation update --- doc/man/ustctl.1 | 76 ++++++++++++++++++++++++++++++++++----- doc/man/ustctl.1.md | 69 +++++++++++++++++++++++++++++++---- doc/man/ustd.1 | 7 ++-- doc/man/ustd.1.md | 4 +++ doc/man/usttrace.1 | 3 ++ doc/man/usttrace.1.md | 5 +++ doc/manual/manual.texinfo | 2 ++ 7 files changed, 148 insertions(+), 18 deletions(-) diff --git a/doc/man/ustctl.1 b/doc/man/ustctl.1 index bb942ae0..e77251d4 100644 --- a/doc/man/ustctl.1 +++ b/doc/man/ustctl.1 @@ -1,7 +1,7 @@ -.\" 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 @@ -10,7 +10,7 @@ \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" @@ -27,7 +27,7 @@ Create trace. . .TP \fB\-\-alloc\-trace\fR -Alloc trace. +Allocate trace. . .TP \fB\-\-start\-trace\fR @@ -43,19 +43,19 @@ Destroy the trace. . .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 @@ -69,9 +69,67 @@ Disable a marker. \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 , 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. diff --git a/doc/man/ustctl.1.md b/doc/man/ustctl.1.md index 12437c51..d0ecb983 100644 --- a/doc/man/ustctl.1.md +++ b/doc/man/ustctl.1.md @@ -7,7 +7,7 @@ ustctl(1) -- a program to control the tracing of userspace applications ## 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 @@ -22,7 +22,7 @@ starting with two dashes(`-'). A summary of options is included below. Create trace. * `--alloc-trace`: - Alloc trace. + Allocate trace. * `--start-trace`: Start tracing. @@ -34,16 +34,16 @@ starting with two dashes(`-'). A summary of options is included below. Destroy the trace. * `--set-subbuf-size` /: - Set the size of subbuffers per channel. + Set the size of subbuffers in CHANNEL. * `--set-subbuf-num` : - 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` : - Get the size of subbuffers per channel. + Print the size of subbuffers per buffer for CHANNEL. * `--get-subbuf-num` : - Get the number of subbuffers per channel. + Print the number of subbuffers per buffer for CHANNEL. * `--enable-marker` /: Enable a marker. @@ -54,9 +54,64 @@ starting with two dashes(`-'). A summary of options is included below. * `--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. diff --git a/doc/man/ustd.1 b/doc/man/ustd.1 index bb7b9823..f4239784 100644 --- a/doc/man/ustd.1 +++ b/doc/man/ustd.1 @@ -1,7 +1,7 @@ -.\" 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 @@ -40,6 +40,9 @@ Write the PID in this file (when using \-d). \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. . diff --git a/doc/man/ustd.1.md b/doc/man/ustd.1.md index 836589e0..296d1c47 100644 --- a/doc/man/ustd.1.md +++ b/doc/man/ustd.1.md @@ -32,6 +32,10 @@ starting with two dashes(`-'). A summary of options is included below. * `-V`, `--version`: Show version of program. +## SEE ALSO + +ustctl(1), usttrace(1) + ## AUTHOR `ustd` was written by Pierre-Marc Fournier. diff --git a/doc/man/usttrace.1 b/doc/man/usttrace.1 index 79cb0a5e..93584a19 100644 --- a/doc/man/usttrace.1 +++ b/doc/man/usttrace.1 @@ -86,6 +86,9 @@ Specify the number of subbuffers. \fB\-W\fR Undocumented option. . +.SH "SEE ALSO" +ustctl(1), ustd(1) +. .SH "AUTHOR" \fBusttrace\fR was written by Pierre\-Marc Fournier. . diff --git a/doc/man/usttrace.1.md b/doc/man/usttrace.1.md index 9961a961..fbe5d927 100644 --- a/doc/man/usttrace.1.md +++ b/doc/man/usttrace.1.md @@ -62,6 +62,11 @@ starting with two dashes(`-'). A summary of options is included below. * `-W`: Undocumented option. +## SEE ALSO + +ustctl(1), ustd(1) + + ## AUTHOR `usttrace` was written by Pierre-Marc Fournier. diff --git a/doc/manual/manual.texinfo b/doc/manual/manual.texinfo index 8254cdb0..385cb35a 100644 --- a/doc/manual/manual.texinfo +++ b/doc/manual/manual.texinfo @@ -418,6 +418,8 @@ $ 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 -- 2.34.1