doc/man/ustctl.1

   1 .\" generated with Ronn/v0.5
   2 .\" http://github.com/rtomayko/ronn/
   3 .
   4 .TH "USTCTL" "1" "August 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\-\-set\-sock\-path\fR
  54 Set the path of the daemon socket.
  55 .
  56 .TP
  57 \fB\-\-get\-subbuf\-size\fR \fICHANNEL\fR
  58 Print the size of subbuffers per buffer for CHANNEL.
  59 .
  60 .TP
  61 \fB\-\-get\-subbuf\-num\fR \fICHANNEL\fR
  62 Print the number of subbuffers per buffer for CHANNEL.
  63 .
  64 .TP
  65 \fB\-\-get\-sock\-path\fR
  66 Get the path of the daemon socket.
  67 .
  68 .TP
  69 \fB\-\-enable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR
  70 Enable a marker.
  71 .
  72 .TP
  73 \fB\-\-disable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR
  74 Disable a marker.
  75 .
  76 .TP
  77 \fB\-\-list\-markers\fR
  78 List the markers of the process, their state and format string.
  79 .
  80 .TP
  81 \fB\-\-force\-switch\fR
  82 Force a subbuffer switch. This will flush all the data currently held.
  83 .
  84 .SH "LIFE CYCLE OF A TRACE"
  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.
  90 .
  91 .P
  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.
  95 .
  96 .P
  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.
 102 .
 103 .P
 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.
 106 .
 107 .P
 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.
 113 .
 114 .P
 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.
 119 .
 120 .SH "STRUCTURE OF A TRACE"
 121 Each instrumentation point that is added in a program is associated to a
 122 channel.
 123 .
 124 .P
 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.
 130 .
 131 .P
 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.
 140 .
 141 .SH "SEE ALSO"
 142 usttrace(1), ustd(1)
 143 .
 144 .SH "AUTHOR"
 145 \fBustctl\fR was written by Pierre\-Marc Fournier.
 146 .
 147 .P
 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.