Propagate default values from configure.ac to asciidoc.conf
[lttng-tools.git] / doc / man / lttng-calibrate.1.txt
CommitLineData
89dbeff8
PP
1lttng-calibrate(1)
2==================
3
4
5NAME
6----
7lttng-calibrate - Quantify LTTng overhead
8
9
10SYNOPSIS
11--------
12[verse]
ce19b9ed 13*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *calibrate*
89dbeff8
PP
14
15
16DESCRIPTION
17-----------
18The `lttng calibrate` commands quantifies the overhead of LTTng tracers.
19
20The `lttng calibrate` command can be used to find out the combined
21average overhead of the LTTng tracers and the instrumentation mechanisms
22used. This overhead can be calibrated in terms of time or using any of
23the PMU performance counter available on the system.
24
25For now, the only implemented calibration is the Linux kernel function
26instrumentation (_kretprobes_).
27
28
29Calibrate Linux kernel function instrumentation
30~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
31
32As an example, we use an i7 processor with 4 general-purpose PMU
33registers. This information is available by issuing `dmesg`, looking
34for `generic registers`.
35
36The following sequence of commands gathers a trace executing a kretprobe
37hooked on an empty function, gathering PMU counters LLC
38(Last Level Cache) misses information (use `lttng add-context --list` to
39get the list of available PMU counters).
40
d4f093aa 41[role="term"]
89dbeff8
PP
42------------------------------------------------------------------------
43lttng create calibrate-function
44lttng enable-event calibrate --kernel \
45 --function=lttng_calibrate_kretprobe
46lttng add-context --kernel --type=perf:cpu:LLC-load-misses \
47 --type=perf:cpu:LLC-store-misses \
48 --type=perf:cpu:LLC-prefetch-misses
49lttng start
50
51for a in $(seq 1 10); do
52 lttng calibrate --kernel --function
53done
54
55lttng destroy
56babeltrace $(ls -1drt ~/lttng-traces/calibrate-function-* | tail -n 1)
57------------------------------------------------------------------------
58
7c1a4458 59The output from man:babeltrace(1) can be saved to a text file and
89dbeff8
PP
60opened in a spreadsheet (for example, in LibreOffice) to focus on the
61per-PMU counter delta between consecutive `calibrate_entry` and
62`calibrate_return` events. Note that these counters are per-CPU, so
63scheduling events would need to be present to account for migration
64between CPUs. Therefore, for calibration purposes, only events staying
65on the same CPU must be considered.
66
67Here's an example of the average result, for the i7, on 10 samples:
68
69[width="40%",options="header"]
70|=============================================================
71| PMU counter | Average | Standard deviation
72| `perf_LLC_load_misses` | 5.0 | 0.577
73| `perf_LLC_store_misses` | 1.6 | 0.516
74| `perf_LLC_prefetch_misses` | 9.0 | 14.742
75|=============================================================
76
77As we can notice, the load and store misses are relatively stable across
78runs (their standard deviation is relatively low) compared to the
79prefetch misses. We could conclude from this information that LLC load
80and store misses can be accounted for quite precisely, but prefetches
81within a function seems to behave too erratically (not much causality
82link between the code executed and the CPU prefetch activity) to be
83accounted for.
84
85
86include::common-cmd-options-head.txt[]
87
88
89Domain
90~~~~~~
91One of:
92
93option:-k, option:--kernel::
94 Quantify LTTng overhead in the Linux kernel domain.
95
96option:-u, option:--userspace::
97 Quantify LTTng overhead in the user space domain.
98
99
100Calibration
101~~~~~~~~~~~
102option:--function::
103 Use dynamic function entry/return probes to calibrate (default).
104+
105This option requires the option:--kernel option.
106
107
108include::common-cmd-help-options.txt[]
109
110
111include::common-cmd-footer.txt[]
112
113
114SEE ALSO
115--------
7c1a4458 116man:lttng(1)
This page took 0.031339 seconds and 5 git commands to generate.