[ust.git] / doc / man / ustctl.1

.\" generated with Ronn/v0.6.6
.\" http://github.com/rtomayko/ronn/
.
.TH "USTCTL" "1" "July 2010" "" ""
.
.SH "NAME"
\fBustctl\fR \- a program to control the tracing of userspace applications
.
.SH "SYNOPSIS"
\fBustctl\fR [\fIcommand\fR] [\fIPIDs\fR]\.\.\.
.
.SH "DESCRIPTION"
\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"
These programs follow the usual GNU command line syntax, with long options starting with two dashes(`\-\')\. A summary of options is included below\.
.
.TP
\fB\-h\fR, \fB\-\-help\fR
Show summary of options\.
.
.TP
\fB\-\-create\-trace\fR
Create trace\.
.
.TP
\fB\-\-alloc\-trace\fR
Allocate trace\.
.
.TP
\fB\-\-start\-trace\fR
Start tracing\.
.
.TP
\fB\-\-stop\-trace\fR
Stop tracing\.
.
.TP
\fB\-\-destroy\-trace\fR
Destroy the trace\.
.
.TP
\fB\-\-set\-subbuf\-size\fR \fICHANNEL\fR/\fIbytes\fR
Set the size of subbuffers in CHANNEL\.
.
.TP
\fB\-\-set\-subbuf\-num\fR \fICHANNEL\fR
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
Print the size of subbuffers per buffer for CHANNEL\.
.
.TP
\fB\-\-get\-subbuf\-num\fR \fICHANNEL\fR
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
Enable a marker\.
.
.TP
\fB\-\-disable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR
Disable a marker\.
.
.TP
\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\.
.
.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 <jbernard@debian\.org>, for the Debian project (and may be used by others)\. It was updated by Pierre\-Marc Fournier\.
Commit	Line	Data
3af38436	1	.\" generated with Ronn/v0.6.6
43550d37 JB	2	.\" http://github.com/rtomayko/ronn/
43550d37 JB	3	.
6b42a59a	4	.TH "USTCTL" "1" "July 2010" "" ""
43550d37 JB	5	.
43550d37 JB	6	.SH "NAME"
3af38436	7	\fBustctl\fR \- a program to control the tracing of userspace applications
43550d37 JB	8	.
43550d37 JB	9	.SH "SYNOPSIS"
3af38436	10	\fBustctl\fR [\fIcommand\fR] [\fIPIDs\fR]\.\.\.
43550d37 JB	11	.
43550d37 JB	12	.SH "DESCRIPTION"
3af38436	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	.
43550d37 JB	15	.SH "OPTIONS"
3af38436	16	These 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
3af38436	20	Show summary of options\.
43550d37 JB	21	.
	22	.TP
	23	\fB\-\-create\-trace\fR
3af38436	24	Create trace\.
43550d37 JB	25	.
	26	.TP
	27	\fB\-\-alloc\-trace\fR
3af38436	28	Allocate trace\.
43550d37 JB	29	.
	30	.TP
	31	\fB\-\-start\-trace\fR
3af38436	32	Start tracing\.
43550d37 JB	33	.
	34	.TP
	35	\fB\-\-stop\-trace\fR
3af38436	36	Stop tracing\.
43550d37 JB	37	.
	38	.TP
	39	\fB\-\-destroy\-trace\fR
3af38436	40	Destroy the trace\.
43550d37 JB	41	.
	42	.TP
	43	\fB\-\-set\-subbuf\-size\fR \fICHANNEL\fR/\fIbytes\fR
3af38436	44	Set the size of subbuffers in CHANNEL\.
43550d37 JB	45	.
	46	.TP
	47	\fB\-\-set\-subbuf\-num\fR \fICHANNEL\fR
3af38436 AH	48	Set the number of subbuffers per buffer for CHANNEL\. Must be a power of 2\.
	49	.
	50	.TP
	51	\fB\-\-set\-sock\-path\fR
	52	Set the path of the daemon socket\.
43550d37 JB	53	.
	54	.TP
	55	\fB\-\-get\-subbuf\-size\fR \fICHANNEL\fR
3af38436	56	Print the size of subbuffers per buffer for CHANNEL\.
43550d37 JB	57	.
	58	.TP
	59	\fB\-\-get\-subbuf\-num\fR \fICHANNEL\fR
3af38436 AH	60	Print the number of subbuffers per buffer for CHANNEL\.
	61	.
	62	.TP
	63	\fB\-\-get\-sock\-path\fR
	64	Get the path of the daemon socket\.
43550d37 JB	65	.
	66	.TP
	67	\fB\-\-enable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR
3af38436	68	Enable a marker\.
43550d37 JB	69	.
	70	.TP
	71	\fB\-\-disable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR
3af38436	72	Disable a marker\.
43550d37 JB	73	.
	74	.TP
	75	\fB\-\-list\-markers\fR
3af38436	76	List the markers of the process, their state and format string\.
43550d37	77	.
6b42a59a AH	78	.TP
	79	\fB\-\-force\-switch\fR
	80	Force a subbuffer switch\. This will flush all the data currently held\.
	81	.
c3947c25	82	.SH "LIFE CYCLE OF A TRACE"
3af38436	83	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\.
c3947c25 PMF	84	.
c3947c25 PMF	85	.P
3af38436	86	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\.
c3947c25 PMF	87	.
c3947c25 PMF	88	.P
3af38436	89	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\.
c3947c25 PMF	90	.
c3947c25 PMF	91	.P
3af38436	92	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\.
c3947c25 PMF	93	.
c3947c25 PMF	94	.P
3af38436	95	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\.
c3947c25 PMF	96	.
c3947c25 PMF	97	.P
3af38436	98	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\.
c3947c25 PMF	99	.
c3947c25 PMF	100	.SH "STRUCTURE OF A TRACE"
3af38436	101	Each instrumentation point that is added in a program is associated to a channel\.
c3947c25 PMF	102	.
c3947c25 PMF	103	.P
3af38436	104	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\.
c3947c25 PMF	105	.
c3947c25 PMF	106	.P
3af38436	107	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\.
c3947c25 PMF	108	.
	109	.SH "SEE ALSO"
	110	usttrace(1), ustd(1)
	111	.
43550d37	112	.SH "AUTHOR"
3af38436	113	\fBustctl\fR was written by Pierre\-Marc Fournier\.
43550d37 JB	114	.
43550d37 JB	115	.P
3af38436	116	This 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\.