| 1 | .\" generated with Ronn/v0.5 |
| 2 | .\" http://github.com/rtomayko/ronn/ |
| 3 | . |
| 4 | .TH "USTCTL" "1" "May 2010" "" "" |
| 5 | . |
| 6 | .SH "NAME" |
| 7 | \fBustctl\fR \-\- a program to control the tracing of userspace applications |
| 8 | . |
| 9 | .SH "SYNOPSIS" |
| 10 | \fBustctl\fR [\fIcommand\fR] [\fIPIDs\fR]... |
| 11 | . |
| 12 | .SH "DESCRIPTION" |
| 13 | \fBustctl\fR is a program to control the tracing of userspace applications. It can |
| 14 | list markers, start the tracing, stop the tracing, enable/disable markers, etc. |
| 15 | . |
| 16 | .SH "OPTIONS" |
| 17 | These programs follow the usual GNU command line syntax, with long options |
| 18 | starting with two dashes(`\-'). A summary of options is included below. |
| 19 | . |
| 20 | .TP |
| 21 | \fB\-h\fR, \fB\-\-help\fR |
| 22 | Show summary of options. |
| 23 | . |
| 24 | .TP |
| 25 | \fB\-\-create\-trace\fR |
| 26 | Create trace. |
| 27 | . |
| 28 | .TP |
| 29 | \fB\-\-alloc\-trace\fR |
| 30 | Allocate trace. |
| 31 | . |
| 32 | .TP |
| 33 | \fB\-\-start\-trace\fR |
| 34 | Start tracing. |
| 35 | . |
| 36 | .TP |
| 37 | \fB\-\-stop\-trace\fR |
| 38 | Stop tracing. |
| 39 | . |
| 40 | .TP |
| 41 | \fB\-\-destroy\-trace\fR |
| 42 | Destroy the trace. |
| 43 | . |
| 44 | .TP |
| 45 | \fB\-\-set\-subbuf\-size\fR \fICHANNEL\fR/\fIbytes\fR |
| 46 | Set the size of subbuffers in CHANNEL. |
| 47 | . |
| 48 | .TP |
| 49 | \fB\-\-set\-subbuf\-num\fR \fICHANNEL\fR |
| 50 | Set the number of subbuffers per buffer for CHANNEL. Must be a power of 2. |
| 51 | . |
| 52 | .TP |
| 53 | \fB\-\-get\-subbuf\-size\fR \fICHANNEL\fR |
| 54 | Print the size of subbuffers per buffer for CHANNEL. |
| 55 | . |
| 56 | .TP |
| 57 | \fB\-\-get\-subbuf\-num\fR \fICHANNEL\fR |
| 58 | Print the number of subbuffers per buffer for CHANNEL. |
| 59 | . |
| 60 | .TP |
| 61 | \fB\-\-enable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR |
| 62 | Enable a marker. |
| 63 | . |
| 64 | .TP |
| 65 | \fB\-\-disable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR |
| 66 | Disable a marker. |
| 67 | . |
| 68 | .TP |
| 69 | \fB\-\-list\-markers\fR |
| 70 | List the markers of the process, their state and format string. |
| 71 | . |
| 72 | .SH "LIFE CYCLE OF A TRACE" |
| 73 | Typically, the first step is to enable markers with \fB\-\-enable\-marker\fR. An |
| 74 | enabled marker generates an event when the control flow passes over it |
| 75 | (assuming the trace is recording). A disabled marker produces nothing. Enabling |
| 76 | and disabling markers may however be done at any point, including while the |
| 77 | trace is being recorded. |
| 78 | . |
| 79 | .P |
| 80 | In order to record events, a trace is first created with \fB\-\-create\-trace\fR. At |
| 81 | this point, the subbuffer count and size may be changed with \fB\-\-set\-subbuf\-num\fR |
| 82 | and \fB\-\-set\-subbuf\-size\fR. |
| 83 | . |
| 84 | .P |
| 85 | Afterward, the trace may be allocated with \fB\-\-alloc\-trace\fR. This allocates the |
| 86 | buffers in memory, so once this is done, the subbuffer size and count can not |
| 87 | be changed. Trace allocation also causes the daemon to connect to the trace |
| 88 | buffers and wait for data to arrive. Explicit allocation is optional, as it is |
| 89 | done automatically at trace start. |
| 90 | . |
| 91 | .P |
| 92 | The trace may then be started with \fB\-\-start\-trace\fR. This results in events |
| 93 | being recorded in the buffer. The daemon automatically collects these events. |
| 94 | . |
| 95 | .P |
| 96 | The trace may be stopped with \fB\-\-stop\-trace\fR, either definitely after all the |
| 97 | wanted information is collected, or temporarily, before being started again |
| 98 | with \fB\-\-start\-trace\fR. This results in effectively "pausing" the recording. |
| 99 | . |
| 100 | .P |
| 101 | Finally, when \fB\-\-destroy\-trace\fR is used, the trace buffers are unallocated. |
| 102 | However, the memory may not be effectively freed until the daemon finishes to |
| 103 | collect them. |
| 104 | . |
| 105 | .SH "STRUCTURE OF A TRACE" |
| 106 | Each instrumentation point that is added in a program is associated to a |
| 107 | channel. |
| 108 | . |
| 109 | .P |
| 110 | Trace events are put in buffers. There is one buffer per channel, per cpu. |
| 111 | For example, on a system with 4 cores and tracing an application with 3 |
| 112 | channels, there will be 12 buffers in total. The content of each of these |
| 113 | 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 |
| 114 | contained the events from the metadata channel and having occurred on cpu 2. |
| 115 | . |
| 116 | .P |
| 117 | In memory, each buffer is divided in subbuffers. Subbuffers are equally\-sized, |
| 118 | contiguous parts of a buffer. The size of a buffer is equal to the number of |
| 119 | subbuffers it contains times the size of each subbuffer. When a subbuffer is |
| 120 | full, it is collected by the daemon while the others are filled. If, however, |
| 121 | the buffer size is too small, buffer overflows may occur and result in event |
| 122 | loss. By default, the number of subbuffers per buffer is 2. Subbuffer size |
| 123 | for a given channel may be chosen with \fB\-\-set\-subbuf\-size\fR while the subbuffer |
| 124 | count is set with \fB\-\-set\-subbuf\-num\fR. |
| 125 | . |
| 126 | .SH "SEE ALSO" |
| 127 | usttrace(1), ustd(1) |
| 128 | . |
| 129 | .SH "AUTHOR" |
| 130 | \fBustctl\fR was written by Pierre\-Marc Fournier. |
| 131 | . |
| 132 | .P |
| 133 | This manual page was written by Jon Bernard <jbernard@debian.org>, for |
| 134 | the Debian project (and may be used by others). It was updated by Pierre\-Marc |
| 135 | Fournier. |