doc/man: create lttng-calibrate(1) and update/fix content

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 36a13bc1dd441c08c9a594827a6de221c5e11f61..2909b67e76e5411c6434355e1413ec01edb75d49 100644 (file)
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -21,7 +21,8 @@ MAN1_NAMES = \
        lttng-enable-channel \
        lttng-disable-channel \
        lttng-add-context \
-       lttng-list
+       lttng-list \
+       lttng-calibrate
 MAN3_NAMES =
 MAN8_NAMES =
 MAN1_NO_ASCIIDOC_NAMES = lttng-crash

diff --git a/doc/man/lttng-calibrate.1.txt b/doc/man/lttng-calibrate.1.txt
new file mode 100644 (file)
index 0000000..71db0e5
--- /dev/null
+++ b/doc/man/lttng-calibrate.1.txt
@@ -0,0 +1,115 @@
+lttng-calibrate(1)
+==================
+
+
+NAME
+----
+lttng-calibrate - Quantify LTTng overhead
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *calibrate*
+
+
+DESCRIPTION
+-----------
+The `lttng calibrate` commands quantifies the overhead of LTTng tracers.
+
+The `lttng calibrate` command can be used to find out the combined
+average overhead of the LTTng tracers and the instrumentation mechanisms
+used. This overhead can be calibrated in terms of time or using any of
+the PMU performance counter available on the system.
+
+For now, the only implemented calibration is the Linux kernel function
+instrumentation (_kretprobes_).
+
+
+Calibrate Linux kernel function instrumentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As an example, we use an i7 processor with 4 general-purpose PMU
+registers. This information is available by issuing `dmesg`, looking
+for `generic registers`.
+
+The following sequence of commands gathers a trace executing a kretprobe
+hooked on an empty function, gathering PMU counters LLC
+(Last Level Cache) misses information (use `lttng add-context --list` to
+get the list of available PMU counters).
+
+------------------------------------------------------------------------
+lttng create calibrate-function
+lttng enable-event calibrate --kernel \
+                             --function=lttng_calibrate_kretprobe
+lttng add-context --kernel --type=perf:cpu:LLC-load-misses \
+                           --type=perf:cpu:LLC-store-misses \
+                           --type=perf:cpu: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)
+------------------------------------------------------------------------
+
+The output from linklttng:babeltrace(1) can be saved to a text file and
+opened in a spreadsheet (for example, in LibreOffice) to focus on the
+per-PMU counter delta between consecutive `calibrate_entry` and
+`calibrate_return` events. Note that these counters are per-CPU, so
+scheduling events would need to be present to account for migration
+between CPUs. Therefore, for calibration purposes, only events staying
+on the same CPU must be considered.
+
+Here's an example of the average result, for the i7, on 10 samples:
+
+[width="40%",options="header"]
+|=============================================================
+| PMU counter                | Average   | Standard deviation
+| `perf_LLC_load_misses`     | 5.0       | 0.577
+| `perf_LLC_store_misses`    | 1.6       | 0.516
+| `perf_LLC_prefetch_misses` | 9.0       | 14.742
+|=============================================================
+
+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. We could 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.
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-k, option:--kernel::
+    Quantify LTTng overhead in the Linux kernel domain.
+
+option:-u, option:--userspace::
+    Quantify LTTng overhead in the user space domain.
+
+
+Calibration
+~~~~~~~~~~~
+option:--function::
+    Use dynamic function entry/return probes to calibrate (default).
++
+This option requires the option:--kernel option.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1)