X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Fustctl.1.md;h=208e1dd88c05b6fb01ff3f0e2de65a3919570852;hb=4a8b1e481a205712205ed75593b8ecea2851e6b3;hp=12437c5191307f6f9531b4e7e0628573c8887ab2;hpb=43550d379ea53556183002632da0d23c0c417d03;p=ust.git diff --git a/doc/man/ustctl.1.md b/doc/man/ustctl.1.md index 12437c5..208e1dd 100644 --- a/doc/man/ustctl.1.md +++ b/doc/man/ustctl.1.md @@ -7,7 +7,7 @@ ustctl(1) -- a program to control the tracing of userspace applications ## 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 @@ -22,7 +22,7 @@ starting with two dashes(`-'). A summary of options is included below. Create trace. * `--alloc-trace`: - Alloc trace. + Allocate trace. * `--start-trace`: Start tracing. @@ -34,16 +34,22 @@ starting with two dashes(`-'). A summary of options is included below. Destroy the trace. * `--set-subbuf-size` /: - Set the size of subbuffers per channel. + Set the size of subbuffers in CHANNEL. * `--set-subbuf-num` : - Set the number of subbuffers per channel. + Set the number of subbuffers per buffer for CHANNEL. Must be a power of 2. + + * `--set-sock-path`: + Set the path of the daemon socket. * `--get-subbuf-size` : - Get the size of subbuffers per channel. + Print the size of subbuffers per buffer for CHANNEL. * `--get-subbuf-num` : - Get the number of subbuffers per channel. + Print the number of subbuffers per buffer for CHANNEL. + + * `--get-sock-path`: + Get the path of the daemon socket. * `--enable-marker` /: Enable a marker. @@ -54,9 +60,70 @@ starting with two dashes(`-'). A summary of options is included below. * `--list-markers`: List the markers of the process, their state and format string. + * `--force-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 `ustd`, 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), ustd(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.