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] | |
13 | *lttng* ['GENERAL OPTIONS'] *calibrate* | |
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 | ||
41 | ------------------------------------------------------------------------ | |
42 | lttng create calibrate-function | |
43 | lttng enable-event calibrate --kernel \ | |
44 | --function=lttng_calibrate_kretprobe | |
45 | lttng add-context --kernel --type=perf:cpu:LLC-load-misses \ | |
46 | --type=perf:cpu:LLC-store-misses \ | |
47 | --type=perf:cpu:LLC-prefetch-misses | |
48 | lttng start | |
49 | ||
50 | for a in $(seq 1 10); do | |
51 | lttng calibrate --kernel --function | |
52 | done | |
53 | ||
54 | lttng destroy | |
55 | babeltrace $(ls -1drt ~/lttng-traces/calibrate-function-* | tail -n 1) | |
56 | ------------------------------------------------------------------------ | |
57 | ||
58 | The output from linklttng:babeltrace(1) can be saved to a text file and | |
59 | opened in a spreadsheet (for example, in LibreOffice) to focus on the | |
60 | per-PMU counter delta between consecutive `calibrate_entry` and | |
61 | `calibrate_return` events. Note that these counters are per-CPU, so | |
62 | scheduling events would need to be present to account for migration | |
63 | between CPUs. Therefore, for calibration purposes, only events staying | |
64 | on the same CPU must be considered. | |
65 | ||
66 | Here's an example of the average result, for the i7, on 10 samples: | |
67 | ||
68 | [width="40%",options="header"] | |
69 | |============================================================= | |
70 | | PMU counter | Average | Standard deviation | |
71 | | `perf_LLC_load_misses` | 5.0 | 0.577 | |
72 | | `perf_LLC_store_misses` | 1.6 | 0.516 | |
73 | | `perf_LLC_prefetch_misses` | 9.0 | 14.742 | |
74 | |============================================================= | |
75 | ||
76 | As we can notice, the load and store misses are relatively stable across | |
77 | runs (their standard deviation is relatively low) compared to the | |
78 | prefetch misses. We could conclude from this information that LLC load | |
79 | and store misses can be accounted for quite precisely, but prefetches | |
80 | within a function seems to behave too erratically (not much causality | |
81 | link between the code executed and the CPU prefetch activity) to be | |
82 | accounted for. | |
83 | ||
84 | ||
85 | include::common-cmd-options-head.txt[] | |
86 | ||
87 | ||
88 | Domain | |
89 | ~~~~~~ | |
90 | One of: | |
91 | ||
92 | option:-k, option:--kernel:: | |
93 | Quantify LTTng overhead in the Linux kernel domain. | |
94 | ||
95 | option:-u, option:--userspace:: | |
96 | Quantify LTTng overhead in the user space domain. | |
97 | ||
98 | ||
99 | Calibration | |
100 | ~~~~~~~~~~~ | |
101 | option:--function:: | |
102 | Use dynamic function entry/return probes to calibrate (default). | |
103 | + | |
104 | This option requires the option:--kernel option. | |
105 | ||
106 | ||
107 | include::common-cmd-help-options.txt[] | |
108 | ||
109 | ||
110 | include::common-cmd-footer.txt[] | |
111 | ||
112 | ||
113 | SEE ALSO | |
114 | -------- | |
115 | linklttng:lttng(1) |