Manpage: cleanup layout of calibrate

[lttng-tools.git] / doc / man / lttng.1

diff --git a/doc/man/lttng.1 b/doc/man/lttng.1
index 99941db93af0d0a5d4436c91bbe230c7d67e70ac..3a358dd78ff21d919a8dd1d6760f5b2ca33866ca 100644 (file)
--- a/doc/man/lttng.1
+++ b/doc/man/lttng.1
@@ -82,9 +82,9 @@ Simple listing of lttng options.
 Simple listing of lttng commands.
 .SH "COMMANDS"
 
-.TP
+.PP
 \fBadd-context\fP
-.nf
+.RS
 Add context to event(s) and/or channel(s).
 
 A context is basically extra information appended to a channel. For instance,
@@ -96,7 +96,10 @@ For example, this command will add the context information 'prio' and two perf
 counters (hardware branch misses and cache misses), to all events in the trace
 data output:
 
-# lttng add-context \-k \-t prio \-t perf:branch-misses \-t perf:cache-misses
+.nf
+# lttng add-context \-k \-t prio \-t perf:branch-misses \\
+               \-t perf:cache-misses
+.fi
 
 Please take a look at the help (\-h/\-\-help) for a detailed list of available
 contexts.
@@ -107,30 +110,34 @@ Otherwise the context will be added only to the given channel (\-c).
 
 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
 file.
-.fi
 
 .B OPTIONS:
 
-.nf
-\-h, \-\-help
-        Show summary of possible options and commands.
-\-s, \-\-session NAME
-        Apply on session name.
-\-c, \-\-channel NAME
-        Apply on channel name.
-\-k, \-\-kernel
-        Apply for the kernel tracer
-\-u, \-\-userspace
-        Apply for the user-space tracer
-\-t, \-\-type TYPE
-        Context type. You can repeat this option on the command line. Please
-        use "lttng add-context \-h" to list all available types.
-.fi
-
-.IP
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-s, \-\-session NAME"
+Apply on session name.
+.TP
+.BR "\-c, \-\-channel NAME"
+Apply on channel name.
+.TP
+.BR "\-k, \-\-kernel"
+Apply for the kernel tracer
+.TP
+.BR "\-u, \-\-userspace"
+Apply for the user-space tracer
+.TP
+.BR "\-t, \-\-type TYPE"
+Context type. You can repeat this option on the command line. Please
+use "lttng add-context \-h" to list all available types.
+.RE
+.PP
 
-.IP "\fBcalibrate\fP"
-.nf
+.PP
+\fBcalibrate\fP [OPTIONS]
+.RS
 Quantify LTTng overhead
 
 The LTTng calibrate command can be used to find out the combined average
@@ -152,16 +159,21 @@ an empty function, gathering PMU counters LLC (Last Level Cache) misses
 information (see lttng add-context \-\-help to see the list of available PMU
 counters).
 
+.nf
 # lttng create calibrate-function
-# lttng enable-event calibrate \-\-kernel \-\-function lttng_calibrate_kretprobe
-# lttng add-context \-\-kernel \-t perf:LLC-load-misses \-t perf:LLC-store-misses \\
-                  \-t perf:LLC-prefetch-misses
+# lttng enable-event calibrate \-\-kernel \\
+       \-\-function lttng_calibrate_kretprobe
+# lttng add-context \-\-kernel \-t perf:LLC-load-misses \\
+       \-t perf:LLC-store-misses \\
+       \-t perf:LLC-prefetch-misses
 # lttng start
 # for a in $(seq 1 10); do \\
         lttng calibrate \-\-kernel \-\-function;
   done
 # lttng destroy
-# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* | tail \-n 1)
+# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* \\
+       | tail \-n 1)
+.fi
 
 The output from babeltrace can be saved to a text file and opened in a
 spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between
@@ -172,10 +184,12 @@ staying on the same CPU must be considered.
 
 The average result, for the i7, on 10 samples:
 
+.nf
                           Average     Std.Dev.
 perf_LLC_load_misses:       5.0       0.577
 perf_LLC_store_misses:      1.6       0.516
 perf_LLC_prefetch_misses:   9.0      14.742
+.fi
 
 As we can notice, the load and store misses are relatively stable across runs
 (their standard deviation is relatively low) compared to the prefetch misses.
@@ -183,22 +197,23 @@ We can conclude from this information that LLC load and store misses can be
 accounted for quite precisely, but prefetches within a function seems to behave
 too erratically (not much causality link between the code executed and the CPU
 prefetch activity) to be accounted for.
-.fi
 
 .B OPTIONS:
 
-.nf
-\-h, \-\-help
-        Show summary of possible options and commands.
-\-k, \-\-kernel
-        Apply for the kernel tracer
-\-u, \-\-userspace
-        Apply for the user-space tracer
-\-\-function
-        Dynamic function entry/return probe (default)
-.fi
-
-.IP
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-k, \-\-kernel"
+Apply for the kernel tracer
+.TP
+.BR "\-u, \-\-userspace"
+Apply for the user-space tracer
+.TP
+.BR "\-\-function"
+Dynamic function entry/return probe (default)
+.RE
+.PP
 
 .IP "\fBcreate\fP [NAME] [OPTIONS]
 .nf
@@ -230,6 +245,13 @@ a non-writeable home directory.
         Simple listing of options
 \-o, \-\-output PATH
         Specify output path for traces
+\-\-no-output
+       Traces will not be outputed
+\-\-snapshot
+       Set the session in snapshot mode. Created in no-output mode
+       and uses the URL, if one, as the default snapshot output.
+       Every channel will be set in overwrite mode and with mmap
+       output (splice not supported).
 
 Using these options, each API call can be controlled individually. For
 instance, \-C does not enable the consumer automatically. You'll need the \-e