-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)
projects / lttng-tools.git / commitdiff
