From c06628dc6498532bc9bf67d05871c34120854417 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Tue, 14 Jun 2016 19:17:06 -0400 Subject: [PATCH] Remove calibrate documentation 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 --- configure.ac | 1 - doc/Makefile.am | 4 +- doc/calibrate.txt | 56 ---------------- doc/man/Makefile.am | 1 - doc/man/asciidoc-attrs.conf.in | 1 - doc/man/lttng-calibrate.1.txt | 116 --------------------------------- doc/man/lttng.1.txt | 3 - 7 files changed, 2 insertions(+), 180 deletions(-) delete mode 100644 doc/calibrate.txt delete mode 100644 doc/man/lttng-calibrate.1.txt diff --git a/configure.ac b/configure.ac index ab72dbe5e..d03305a0b 100644 --- a/configure.ac +++ b/configure.ac @@ -271,7 +271,6 @@ _AC_DEFINE_QUOTED_AND_SUBST([DEFAULT_NETWORK_VIEWER_BIND_ADDRESS], [localhost]) # Command short descriptions _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_CONTEXT], [Add context fields to a channel]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CALIBRATE], [Quantify LTTng overhead]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CREATE], [Create a tracing session]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DESTROY], [Tear down tracing sessions]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_CHANNEL], [Disable tracing channels]) diff --git a/doc/Makefile.am b/doc/Makefile.am index 7ae930356..045170937 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,9 +1,9 @@ SUBDIRS = man EXTRA_DIST = quickstart.txt streaming-howto.txt python-howto.txt \ - snapshot-howto.txt calibrate.txt kernel-CodingStyle.txt \ + snapshot-howto.txt kernel-CodingStyle.txt \ live-reading-howto.txt live-reading-protocol.txt \ relayd-architecture.txt dist_doc_DATA = quickstart.txt streaming-howto.txt python-howto.txt \ - snapshot-howto.txt calibrate.txt live-reading-howto.txt \ + snapshot-howto.txt live-reading-howto.txt \ live-reading-protocol.txt valgrind-howto.txt diff --git a/doc/calibrate.txt b/doc/calibrate.txt deleted file mode 100644 index e37075f02..000000000 --- a/doc/calibrate.txt +++ /dev/null @@ -1,56 +0,0 @@ -LTTng calibrate command documentation -Mathieu Desnoyers, August 6, 2011 - -The LTTng calibrate command can be used to find out the combined average -overhead of the LTTng tracer 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 calibration implemented is that of the kernel function -instrumentation (kretprobes). - - -* Calibrate kernel function instrumentation - -Let's use an example to show this calibration. We use an i7 processor -with 4 general-purpose PMU registers. This information is available by -issuing dmesg, looking for "generic registers". - -This sequence of commands will gather a trace executing a kretprobe -hooked on 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). - -(as root) -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 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 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 -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 CPU. Therefore, for calibration -purposes, only events staying on the same CPU must be considered. - -The average result, for the i7, on 10 samples: - - 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 - -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 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. diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 8c1472e87..9c7f125d0 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -21,7 +21,6 @@ MAN1_NAMES = \ lttng-disable-channel \ lttng-add-context \ lttng-list \ - lttng-calibrate \ lttng-track \ lttng-untrack \ lttng-status \ diff --git a/doc/man/asciidoc-attrs.conf.in b/doc/man/asciidoc-attrs.conf.in index 83f59cd72..a3d0c3ac7 100644 --- a/doc/man/asciidoc-attrs.conf.in +++ b/doc/man/asciidoc-attrs.conf.in @@ -40,7 +40,6 @@ system_lttng_conf="@CONFDIR@/lttng/lttng.conf" # command short descriptions cmd_descr_add_context="@CMD_DESCR_ADD_CONTEXT@" -cmd_descr_calibrate="@CMD_DESCR_CALIBRATE@" cmd_descr_create="@CMD_DESCR_CREATE@" cmd_descr_destroy="@CMD_DESCR_DESTROY@" cmd_descr_disable_channel="@CMD_DESCR_DISABLE_CHANNEL@" diff --git a/doc/man/lttng-calibrate.1.txt b/doc/man/lttng-calibrate.1.txt deleted file mode 100644 index 02195b85d..000000000 --- a/doc/man/lttng-calibrate.1.txt +++ /dev/null @@ -1,116 +0,0 @@ -lttng-calibrate(1) -================== - - -NAME ----- -lttng-calibrate - Quantify LTTng overhead - - -SYNOPSIS --------- -[verse] -*lttng* ['linkgenoptions:(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). - -[role="term"] ------------------------------------------------------------------------- -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 man: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 --------- -man:lttng(1) diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt index 55359186f..748ccf9a2 100644 --- a/doc/man/lttng.1.txt +++ b/doc/man/lttng.1.txt @@ -219,9 +219,6 @@ man:lttng-untrack(1):: Miscellaneous ~~~~~~~~~~~~~ -man:lttng-calibrate(1):: - {cmd_descr_calibrate}. - man:lttng-help(1):: {cmd_descr_help}. -- 2.34.1