From 89dbeff8bc1e862192f8bec4a89d53b9098cc824 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Fri, 13 Nov 2015 23:58:11 -0500 Subject: [PATCH] doc/man: create lttng-calibrate(1) and update/fix content MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- doc/man/Makefile.am | 3 +- doc/man/lttng-calibrate.1.txt | 115 ++++++++++++++++++++++++++++++++++ 2 files changed, 117 insertions(+), 1 deletion(-) create mode 100644 doc/man/lttng-calibrate.1.txt diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 36a13bc1d..2909b67e7 100644 --- 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 index 000000000..71db0e50c --- /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) -- 2.34.1