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