X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=doc%2Fman%2Fustctl.1.md;h=89a952ac33a9e5f6b58824053183bb485d5636cc;hb=eb78cc5f9e75f620e9037708874f88b0a17e4ed8;hp=12437c5191307f6f9531b4e7e0628573c8887ab2;hpb=43550d379ea53556183002632da0d23c0c417d03;p=lttng-ust.git diff --git a/doc/man/ustctl.1.md b/doc/man/ustctl.1.md index 12437c51..89a952ac 100644 --- a/doc/man/ustctl.1.md +++ b/doc/man/ustctl.1.md @@ -3,11 +3,11 @@ ustctl(1) -- a program to control the tracing of userspace applications ## SYNOPSIS -`ustctl` [] []... +`ustctl` [] []... ## DESCRIPTION -`ustclt` is a program to control the tracing of userspace applications. It can +`ustctl` is a program to control the tracing of userspace applications. It can list markers, start the tracing, stop the tracing, enable/disable markers, etc. ## OPTIONS @@ -16,47 +16,119 @@ These programs follow the usual GNU command line syntax, with long options starting with two dashes(`-'). A summary of options is included below. * `-h`, `--help`: - Show summary of options. + Show summary of commands. - * `--create-trace`: +## COMMANDS + +`ustctl` accepts commands followed by arguments for each respective command. +Most commands require the pid of the application being traced. + + * `create-trace` : Create trace. - * `--alloc-trace`: - Alloc trace. + * `alloc-trace` : + Allocate trace. - * `--start-trace`: + * `start-trace` : Start tracing. - * `--stop-trace`: + * `stop-trace` : Stop tracing. - * `--destroy-trace`: + * `destroy-trace` : Destroy the trace. - * `--set-subbuf-size` /: - Set the size of subbuffers per channel. + * `set-subbuf-size` /: + Set the size of subbuffers in CHANNEL. + + * `set-subbuf-num` /: + Set the number of subbuffers per buffer for CHANNEL. Must be a power of 2. - * `--set-subbuf-num` : - Set the number of subbuffers per channel. + * `set-sock-path` : + Set the path of the daemon socket. - * `--get-subbuf-size` : - Get the size of subbuffers per channel. + * `get-subbuf-size` : + Print the size of subbuffers per buffer for CHANNEL. - * `--get-subbuf-num` : - Get the number of subbuffers per channel. + * `get-subbuf-num` : + Print the number of subbuffers per buffer for CHANNEL. - * `--enable-marker` /: + * `get-sock-path` : + Get the path of the daemon socket. + + * `enable-marker` /: Enable a marker. - * `--disable-marker` /: + * `disable-marker` /: Disable a marker. - * `--list-markers`: + * `list-markers` : List the markers of the process, their state and format string. + * `force-subbuf-switch` : + Force a subbuffer switch. This will flush all the data currently held. + +## LIFE CYCLE OF A TRACE + +Typically, the first step is to enable markers with `enable-marker`. 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. + +In order to record events, a trace is first created with `create-trace`. At +this point, the subbuffer count and size may be changed with `set-subbuf-num` +and `set-subbuf-size`. + +Afterward, the trace may be allocated with `alloc-trace`. 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. + +The trace may then be started with `start-trace`. This results in events +being recorded in the buffer. The daemon automatically collects these events. + +The trace may be stopped with `stop-trace`, either definitely after all the +wanted information is collected, or temporarily, before being started again +with `start-trace`. This results in effectively 'pausing' the recording. +After using `stop-trace`, if a daemon is collecting the trace, it may not +have flushed to the disk the full contents of the buffer yet. + +Finally, when `destroy-trace` is used, the trace buffers are unallocated. +However, the memory may not be effectively freed until the daemon finishes to +collect them. When the trace is being collected by `ust-consumerd`, this command +guarantees its full contents is flushed to the disk. + +## STRUCTURE OF A TRACE + +Each instrumentation point that is added in a program is associated to a +channel. + +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 +`metadata_2` file contains the data that was extracted from the buffer that +contained the events from the metadata channel and having occurred on cpu 2. + +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 `set-subbuf-size` while the subbuffer +count is set with `set-subbuf-num`. + +## SEE ALSO + +usttrace(1), ust-consumerd(1) + ## AUTHOR `ustctl` was written by Pierre-Marc Fournier. This manual page was written by Jon Bernard <jbernard@debian.org>, for -the Debian project (and may be used by others). +the Debian project (and may be used by others). It was updated by Pierre-Marc +Fournier.