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