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"
 
 Simple listing of lttng commands.
 .SH "COMMANDS"
 

-.TP
+.PP

 \fBadd-context\fP
 \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,
 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:
 
 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.
 
 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.
 
 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
 file.

-.fi

 
 .B OPTIONS:
 
 
 .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
 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).
 
 information (see lttng add-context \-\-help to see the list of available PMU
 counters).
 

+.nf

 # lttng create calibrate-function
 # 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
 # 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
 
 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:
 
 
 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
                           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.
 
 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.
 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:
 
 
 .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
 
 .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
         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
 
 Using these options, each API call can be controlled individually. For
 instance, \-C does not enable the consumer automatically. You'll need the \-e