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