| 1 |
.TH STAP-PROFILE-ANNOTATE 1 |
| 2 |
.SH NAME |
| 3 |
stap-profile-annotate \- Annotate source files of running programs. |
| 4 |
|
| 5 |
.\" macros |
| 6 |
.\" do not nest SAMPLEs |
| 7 |
.de SAMPLE |
| 8 |
.br |
| 9 |
|
| 10 |
.nr oldin \\n(.i |
| 11 |
.nf |
| 12 |
.nh |
| 13 |
.. |
| 14 |
.de ESAMPLE |
| 15 |
.hy |
| 16 |
.fi |
| 17 |
.in \\n[oldin]u |
| 18 |
|
| 19 |
.. |
| 20 |
|
| 21 |
.SH SYNOPSIS |
| 22 |
|
| 23 |
.br |
| 24 |
.B strace-profile-annotate [ \fIOPTIONS\fR ] \-d \fIBINARY\fR ... |
| 25 |
.br |
| 26 |
.B strace-profile-annotate [ \fIOPTIONS\fR ] \-x \fIPID\fR |
| 27 |
.br |
| 28 |
.B strace-profile-annotate [ \fIOPTIONS\fR ] \-c \fICMD\fR |
| 29 |
|
| 30 |
.SH DESCRIPTION |
| 31 |
|
| 32 |
The stap-profile-annotate command profiles selected user-space |
| 33 |
processes, based on selected profiling events over a selected period |
| 34 |
of time, then produces an annotated source code listings from all the |
| 35 |
hits on their executables & shared libraries. The annotation |
| 36 |
identifes number of profiling event hits on the source files' |
| 37 |
individual lines. |
| 38 |
|
| 39 |
The selection of user-space processes and shared libraries may be |
| 40 |
system-wide (in which case use the \fB-d\fP option to enumerate all |
| 41 |
potentially interesting binaries), or may be focused on single |
| 42 |
pre-existing process (\fB-x\fP) or a newly run process hierarchy |
| 43 |
(\fB-c\fP). SystemTap automatically adds dependent shared libraries |
| 44 |
for any binary explicitly given by the user. |
| 45 |
|
| 46 |
The selection of profiling event may be the default kernel profiling |
| 47 |
timer (a few hundred Hz), or any desired set of systemtap probe |
| 48 |
points (\fB-e\fP). |
| 49 |
|
| 50 |
The selected time for the profiling session can be the lifetime of the |
| 51 |
targeted process, or a specified timeout (\fB-T\fP), or may be |
| 52 |
interrupted by the user at any time. |
| 53 |
|
| 54 |
The stap-profile-annotate program uses debuginfod to fetch debuginfo |
| 55 |
and source files, and therefore requires a configured |
| 56 |
\fBdebuginfod-find\fP program. If profiling locally built programs |
| 57 |
that are not available in central debuginfod servers, consider |
| 58 |
running a local private server temporarily, possibly federated to |
| 59 |
upstream debuginfod servers. |
| 60 |
.SAMPLE |
| 61 |
% export DEBUGINFOD_URLS=https://UPSTREAM.SERVER/ |
| 62 |
% debuginfod -p 8002 -d :memory: -F /BUILD/TREE1 /BUILD/TREE2 & |
| 63 |
|
| 64 |
# export DEBUGINFOD_URLS=http://localhost:8002/ |
| 65 |
# stap-profile-annotate [...] |
| 66 |
.ESAMPLE |
| 67 |
|
| 68 |
The resulting annotated source files may be written into |
| 69 |
subdirectories based on the buildid of the binaries, or printed to |
| 70 |
standard output (\fB-p\fP). |
| 71 |
|
| 72 |
A profiling session can end before the process it's targeting |
| 73 |
finishes. In this case, sending SIGINT to stap-profile-annotate |
| 74 |
will yield the script's desired output if sent after |
| 75 |
"Stopped stap data collector" is in stdout. You must still |
| 76 |
manually kill the targeted process after sending |
| 77 |
stap-profile-annotate SIGINT. |
| 78 |
|
| 79 |
When stap is run it adds user-space libraries into the kernel |
| 80 |
module by default. However, when profiling a module which is not a |
| 81 |
user-space shared library the -d option must be used to add that |
| 82 |
module's information into the SystemTap kernel module. |
| 83 |
|
| 84 |
stap-profile-annotate relies heavily on the use of debuginfod. Debuginfod |
| 85 |
allows the script to fetch debuginfo and translate virtual memory |
| 86 |
offsets into source line numbers. It is also used to fetch the |
| 87 |
actual source files to annotate. For these reasons, ensure your |
| 88 |
debuginfod client is properly configured for use. |
| 89 |
|
| 90 |
.SH OPTIONS |
| 91 |
.PP |
| 92 |
|
| 93 |
.TP |
| 94 |
.B \fB\-h\fR |
| 95 |
Show help message. |
| 96 |
|
| 97 |
.TP |
| 98 |
.B \fB\-x\fR, \fB\-\-pid\fR \fIPID\fR |
| 99 |
Pre-existing process PID for SystemTap to target. Its symbol information |
| 100 |
is automatically included. |
| 101 |
|
| 102 |
.TP |
| 103 |
.B \fB\-c\fR, \fB\-\-cmd\fR \fICMD\fR |
| 104 |
Command for SystemTap to run and then target. Its symbol information |
| 105 |
is automatically included. |
| 106 |
|
| 107 |
.TP |
| 108 |
.B \fB\-d\fR \fIBINARY\fR |
| 109 |
Add symbol information for another binary (executable or shared library) |
| 110 |
and its referenced libraries. This option may be repeated. |
| 111 |
|
| 112 |
.TP |
| 113 |
.B \fB\-e\fR \fIEVENTS\fR, \fB\-\-events \fIEVENTS\fR |
| 114 |
Use the given SystemTap probe points (comma-separated), instead of the |
| 115 |
default \fItimer.profile\fP to catch profiling hits. Consider |
| 116 |
\fIperf.hw.branch_misses\fP. |
| 117 |
|
| 118 |
.TP |
| 119 |
.B \fB\-T\fR, \fB\-\-timeout \fITIMEOUT\fR |
| 120 |
stap-profile-annotate will exit after TIMEOUT seconds. \fBNote:\fR if |
| 121 |
\fB\-x\fR or \fB\-c\fR, any targeted processes will not be killed |
| 122 |
after this timeout. Targeted processes either need their own |
| 123 |
timeouts specified or to be killed manually. |
| 124 |
|
| 125 |
.TP |
| 126 |
.B \fB\-p\fR, \fB\-\-print\fR |
| 127 |
Print annotated source files to standard output instead of to |
| 128 |
individual files named like \fIprofile-BUILDID/source/PATH/FOO.c\fP. |
| 129 |
|
| 130 |
.TP |
| 131 |
.B \fB\-w\fR, \fB\-\-context\-width\fR \fIWIDTH\fR |
| 132 |
This option limits the number of lines of context before and |
| 133 |
after each hit source line. Without this option, the default is |
| 134 |
to use unlimited context, i.e., print all lines. |
| 135 |
|
| 136 |
.TP |
| 137 |
.B \fB\-s\fR, \fB\-\-stap\fR \fIPATH\fR |
| 138 |
Override the path to the systemtap program. |
| 139 |
|
| 140 |
.TP |
| 141 |
.B \fB\-v\fR, \fB\-\-verbose\fR |
| 142 |
Increase verbosity. May be repeated for more verbosity. |
| 143 |
|
| 144 |
.SH EXAMPLES |
| 145 |
|
| 146 |
.SS Command |
| 147 |
|
| 148 |
.SAMPLE |
| 149 |
export DEBUGINFOD_URLS=https://debuginfod.elfutils.org/ # if needed |
| 150 |
stap-profile-annotate -w 1 -c '/usr/bin/stress -t 5 --cpu 2' |
| 151 |
.ESAMPLE |
| 152 |
|
| 153 |
.SS Output |
| 154 |
|
| 155 |
.SAMPLE |
| 156 |
Starting stap data collector. |
| 157 |
stress: info: [88582] dispatching hogs: 4 cpu, 0 io, 0 vm, 0 hdd |
| 158 |
stress: info: [88582] successful run completed in 5s |
| 159 |
Counted 19798 known userspace hits. |
| 160 |
Ignored 12342 kernel hits. |
| 161 |
Stopped stap data collector. |
| 162 |
Consumed 321 profile records of 19798 hits across 3 buildids. |
| 163 |
0001228 (6.20%) hits in profile-10da92de76b289c2e9cfb145ca1edc4e850ec4da/source/usr/src/debug/ |
| 164 |
glibc-2.32-10.fc33.x86_64/stdlib/rand.c over 3 lines. |
| 165 |
0004241 (21.42%) hits in profile-10da92de76b289c2e9cfb145ca1edc4e850ec4da/source/usr/src/debug/ |
| 166 |
glibc-2.32-10.fc33.x86_64/stdlib/random_r.c over 18 lines. |
| 167 |
0000094 (0.47%) hits in profile-10da92de76b289c2e9cfb145ca1edc4e850ec4da/source/usr/src/debug/ |
| 168 |
glibc-2.32-10.fc33.x86_64/stdlib/../sysdeps/unix/sysv/linux/x86/lowlevellock.h over 1 lines. |
| 169 |
0004769 (24.09%) hits in profile-10da92de76b289c2e9cfb145ca1edc4e850ec4da/source/usr/src/debug/ |
| 170 |
glibc-2.32-10.fc33.x86_64/stdlib/random.c over 6 lines. |
| 171 |
0001401 (7.08%) hits in profile-520e2b0352d6ac72cb3b58df4f44137e29a94250/source/usr/src/debug/ |
| 172 |
stress-1.0.4-26.fc33.x86_64/src/stress.c over 1 lines. |
| 173 |
00001038 (5.24%) hits in buildid 520e2b0352d6ac72cb3b58df4f44137e29a94250 with unknown source |
| 174 |
0003109 (15.70%) hits in profile-07ae52cfc7f4eda1d13383c04564e3236e059993/source/usr/src/debug/ |
| 175 |
glibc-2.32-10.fc33.x86_64/math/../sysdeps/ieee754/dbl-64/e_sqrt.c over 3 lines. |
| 176 |
0003918 (19.79%) hits in profile-07ae52cfc7f4eda1d13383c04564e3236e059993/source/usr/src/debug/ |
| 177 |
glibc-2.32-10.fc33.x86_64/math/w_sqrt_compat.c over 3 lines. |
| 178 |
.ESAMPLE |
| 179 |
|
| 180 |
.SS Example Annotated Source File |
| 181 |
|
| 182 |
Found in: \fBprofile-07ae52cfc7f4eda1d13383c04564e3236e059993/source/\fR |
| 183 |
\fBusr/src/debug/glibc-2.32-10.fc33.x86_64/math/w_sqrt_compat.c\fR |
| 184 |
|
| 185 |
.SAMPLE |
| 186 |
{ |
| 187 |
0000730 if (__builtin_expect (isless (x, 0.0), 0) && _LIB_VERSION != _IEEE_) |
| 188 |
0000353 return __kernel_standard (x, x, 26); /* sqrt(negative) */ |
| 189 |
|
| 190 |
0002799 return __ieee754_sqrt (x); |
| 191 |
} |
| 192 |
libm_alias_double (__sqrt, sqrt) |
| 193 |
.ESAMPLE |
| 194 |
|
| 195 |
|
| 196 |
.SH SEE ALSO |
| 197 |
.nh |
| 198 |
.nf |
| 199 |
.IR stap (1), |
| 200 |
.IR stapprobes (3stap), |
| 201 |
.IR debuginfod-find (1) |