X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Fustctl.1;h=4f171c61ecd247c192852265ac275334d9c6f8ee;hb=4a8b1e481a205712205ed75593b8ecea2851e6b3;hp=bb942ae0a5de53db5d736016aa52d2f5c726d525;hpb=43550d379ea53556183002632da0d23c0c417d03;p=ust.git diff --git a/doc/man/ustctl.1 b/doc/man/ustctl.1 index bb942ae..4f171c6 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" "August 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,27 @@ 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\-\-set\-sock\-path\fR +Set the path of the daemon socket. . .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\-\-get\-sock\-path\fR +Get the path of the daemon socket. . .TP \fB\-\-enable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR @@ -69,9 +77,74 @@ Disable a marker. \fB\-\-list\-markers\fR List the markers of the process, their state and format string. . +.TP +\fB\-\-force\-switch\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 \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. +After using \fB\-\-stop\-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 \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. When the trace is being collected by \fBustd\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 \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.