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