Update documentation for new ustctl cli
[ust.git] / doc / man / ustctl.1
CommitLineData
eb78cc5f
NC
1.\" generated with Ronn/v0.7.3
2.\" http://github.com/rtomayko/ronn/tree/0.7.3
43550d37 3.
eb78cc5f 4.TH "USTCTL" "1" "January 2011" "" ""
43550d37
JB
5.
6.SH "NAME"
eb78cc5f 7\fBustctl\fR \- a program to control the tracing of userspace applications
43550d37
JB
8.
9.SH "SYNOPSIS"
eb78cc5f 10\fBustctl\fR [\fICOMMAND\fR] [\fIARGS\fR]\.\.\.
43550d37
JB
11.
12.SH "DESCRIPTION"
eb78cc5f 13\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\.
43550d37
JB
14.
15.SH "OPTIONS"
eb78cc5f 16These programs follow the usual GNU command line syntax, with long options starting with two dashes(`\-\')\. A summary of options is included below\.
43550d37
JB
17.
18.TP
19\fB\-h\fR, \fB\-\-help\fR
eb78cc5f
NC
20Show summary of commands\.
21.
22.SH "COMMANDS"
23\fBustctl\fR accepts commands followed by arguments for each respective command\. Most commands require the pid of the application being traced\.
43550d37
JB
24.
25.TP
eb78cc5f
NC
26\fBcreate\-trace\fR \fIPID\fR \fITRACE\fR
27Create trace\.
43550d37
JB
28.
29.TP
eb78cc5f
NC
30\fBalloc\-trace\fR \fIPID\fR \fITRACE\fR
31Allocate trace\.
43550d37
JB
32.
33.TP
eb78cc5f
NC
34\fBstart\-trace\fR \fIPID\fR \fITRACE\fR
35Start tracing\.
43550d37
JB
36.
37.TP
eb78cc5f
NC
38\fBstop\-trace\fR \fIPID\fR \fITRACE\fR
39Stop tracing\.
43550d37
JB
40.
41.TP
eb78cc5f
NC
42\fBdestroy\-trace\fR \fIPID\fR \fITRACE\fR
43Destroy the trace\.
43550d37
JB
44.
45.TP
eb78cc5f
NC
46\fBset\-subbuf\-size\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fIbytes\fR
47Set the size of subbuffers in CHANNEL\.
43550d37
JB
48.
49.TP
eb78cc5f
NC
50\fBset\-subbuf\-num\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fInr\fR
51Set the number of subbuffers per buffer for CHANNEL\. Must be a power of 2\.
3af38436
AH
52.
53.TP
eb78cc5f
NC
54\fBset\-sock\-path\fR \fIPID\fR \fISOCKPATH\fR
55Set the path of the daemon socket\.
43550d37
JB
56.
57.TP
eb78cc5f
NC
58\fBget\-subbuf\-size\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR
59Print the size of subbuffers per buffer for CHANNEL\.
43550d37
JB
60.
61.TP
eb78cc5f
NC
62\fBget\-subbuf\-num\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR
63Print the number of subbuffers per buffer for CHANNEL\.
3af38436
AH
64.
65.TP
eb78cc5f
NC
66\fBget\-sock\-path\fR \fIPID\fR
67Get the path of the daemon socket\.
43550d37
JB
68.
69.TP
eb78cc5f
NC
70\fBenable\-marker\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fIMARKER\fR
71Enable a marker\.
43550d37
JB
72.
73.TP
eb78cc5f
NC
74\fBdisable\-marker\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fIMARKER\fR
75Disable a marker\.
43550d37
JB
76.
77.TP
eb78cc5f
NC
78\fBlist\-markers\fR \fIPID\fR
79List the markers of the process, their state and format string\.
43550d37 80.
6b42a59a 81.TP
eb78cc5f
NC
82\fBforce\-subbuf\-switch\fR \fIPID\fR \fITRACE\fR
83Force a subbuffer switch\. This will flush all the data currently held\.
6b42a59a 84.
c3947c25 85.SH "LIFE CYCLE OF A TRACE"
eb78cc5f 86Typically, the first step is to enable markers with \fBenable\-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\.
c3947c25
PMF
87.
88.P
eb78cc5f 89In order to record events, a trace is first created with \fBcreate\-trace\fR\. At this point, the subbuffer count and size may be changed with \fBset\-subbuf\-num\fR and \fBset\-subbuf\-size\fR\.
c3947c25
PMF
90.
91.P
eb78cc5f 92Afterward, the trace may be allocated with \fBalloc\-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\.
c3947c25
PMF
93.
94.P
eb78cc5f 95The trace may then be started with \fBstart\-trace\fR\. This results in events being recorded in the buffer\. The daemon automatically collects these events\.
c3947c25
PMF
96.
97.P
eb78cc5f 98The trace may be stopped with \fBstop\-trace\fR, either definitely after all the wanted information is collected, or temporarily, before being started again with \fBstart\-trace\fR\. This results in effectively \'pausing\' the recording\. After using \fBstop\-trace\fR, if a daemon is collecting the trace, it may not have flushed to the disk the full contents of the buffer yet\.
c3947c25
PMF
99.
100.P
eb78cc5f 101Finally, when \fBdestroy\-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 \fBust\-consumerd\fR, this command guarantees its full contents is flushed to the disk\.
c3947c25
PMF
102.
103.SH "STRUCTURE OF A TRACE"
eb78cc5f 104Each instrumentation point that is added in a program is associated to a channel\.
c3947c25
PMF
105.
106.P
eb78cc5f 107Trace 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\.
c3947c25
PMF
108.
109.P
eb78cc5f 110In 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 \fBset\-subbuf\-size\fR while the subbuffer count is set with \fBset\-subbuf\-num\fR\.
c3947c25
PMF
111.
112.SH "SEE ALSO"
eb78cc5f 113usttrace(1), ust\-consumerd(1)
c3947c25 114.
43550d37 115.SH "AUTHOR"
eb78cc5f 116\fBustctl\fR was written by Pierre\-Marc Fournier\.
43550d37
JB
117.
118.P
eb78cc5f 119This manual page was written by Jon Bernard <jbernard@debian\.org>, for the Debian project (and may be used by others)\. It was updated by Pierre\-Marc Fournier\.
This page took 0.032316 seconds and 4 git commands to generate.