Commit | Line | Data |
---|---|---|
43550d37 JB |
1 | ustctl(1) -- a program to control the tracing of userspace applications |
2 | ======================================================================= | |
3 | ||
4 | ## SYNOPSIS | |
5 | ||
eb78cc5f | 6 | `ustctl` [<COMMAND>] [<ARGS>]... |
43550d37 JB |
7 | |
8 | ## DESCRIPTION | |
9 | ||
c3947c25 | 10 | `ustctl` is a program to control the tracing of userspace applications. It can |
43550d37 JB |
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`: | |
eb78cc5f | 19 | Show summary of commands. |
43550d37 | 20 | |
eb78cc5f NC |
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>: | |
43550d37 JB |
27 | Create trace. |
28 | ||
eb78cc5f | 29 | * `alloc-trace` <PID> <TRACE>: |
c3947c25 | 30 | Allocate trace. |
43550d37 | 31 | |
eb78cc5f | 32 | * `start-trace` <PID> <TRACE>: |
43550d37 JB |
33 | Start tracing. |
34 | ||
eb78cc5f | 35 | * `stop-trace` <PID> <TRACE>: |
43550d37 JB |
36 | Stop tracing. |
37 | ||
eb78cc5f | 38 | * `destroy-trace` <PID> <TRACE>: |
43550d37 JB |
39 | Destroy the trace. |
40 | ||
eb78cc5f | 41 | * `set-subbuf-size` <PID> <TRACE> <CHANNEL>/<bytes>: |
c3947c25 | 42 | Set the size of subbuffers in CHANNEL. |
43550d37 | 43 | |
eb78cc5f | 44 | * `set-subbuf-num` <PID> <TRACE> <CHANNEL>/<nr>: |
c3947c25 | 45 | Set the number of subbuffers per buffer for CHANNEL. Must be a power of 2. |
43550d37 | 46 | |
eb78cc5f | 47 | * `set-sock-path` <PID> <SOCKPATH>: |
3af38436 AH |
48 | Set the path of the daemon socket. |
49 | ||
eb78cc5f | 50 | * `get-subbuf-size` <PID> <TRACE> <CHANNEL>: |
c3947c25 | 51 | Print the size of subbuffers per buffer for CHANNEL. |
43550d37 | 52 | |
eb78cc5f | 53 | * `get-subbuf-num` <PID> <TRACE> <CHANNEL>: |
c3947c25 | 54 | Print the number of subbuffers per buffer for CHANNEL. |
43550d37 | 55 | |
eb78cc5f | 56 | * `get-sock-path` <PID>: |
3af38436 AH |
57 | Get the path of the daemon socket. |
58 | ||
eb78cc5f | 59 | * `enable-marker` <PID> <TRACE> <CHANNEL>/<MARKER>: |
43550d37 JB |
60 | Enable a marker. |
61 | ||
eb78cc5f | 62 | * `disable-marker` <PID> <TRACE> <CHANNEL>/<MARKER>: |
43550d37 JB |
63 | Disable a marker. |
64 | ||
eb78cc5f | 65 | * `list-markers` <PID>: |
43550d37 JB |
66 | List the markers of the process, their state and format string. |
67 | ||
eb78cc5f | 68 | * `force-subbuf-switch` <PID> <TRACE>: |
6b42a59a AH |
69 | Force a subbuffer switch. This will flush all the data currently held. |
70 | ||
c3947c25 PMF |
71 | ## LIFE CYCLE OF A TRACE |
72 | ||
eb78cc5f | 73 | Typically, the first step is to enable markers with `enable-marker`. An |
c3947c25 PMF |
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 | ||
eb78cc5f NC |
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`. | |
c3947c25 | 82 | |
eb78cc5f | 83 | Afterward, the trace may be allocated with `alloc-trace`. This allocates the |
c3947c25 PMF |
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 | ||
eb78cc5f | 89 | The trace may then be started with `start-trace`. This results in events |
c3947c25 PMF |
90 | being recorded in the buffer. The daemon automatically collects these events. |
91 | ||
eb78cc5f | 92 | The trace may be stopped with `stop-trace`, either definitely after all the |
c3947c25 | 93 | wanted information is collected, or temporarily, before being started again |
eb78cc5f NC |
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 | |
4a8b1e48 | 96 | have flushed to the disk the full contents of the buffer yet. |
c3947c25 | 97 | |
eb78cc5f | 98 | Finally, when `destroy-trace` is used, the trace buffers are unallocated. |
c3947c25 | 99 | However, the memory may not be effectively freed until the daemon finishes to |
9dc7b7ff | 100 | collect them. When the trace is being collected by `ust-consumerd`, this command |
4a8b1e48 | 101 | guarantees its full contents is flushed to the disk. |
c3947c25 PMF |
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 | |
eb78cc5f NC |
121 | for a given channel may be chosen with `set-subbuf-size` while the subbuffer |
122 | count is set with `set-subbuf-num`. | |
c3947c25 PMF |
123 | |
124 | ## SEE ALSO | |
125 | ||
9dc7b7ff | 126 | usttrace(1), ust-consumerd(1) |
c3947c25 | 127 | |
43550d37 JB |
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 | |
c3947c25 PMF |
133 | the Debian project (and may be used by others). It was updated by Pierre-Marc |
134 | Fournier. |