Debian Codegraph @

man/stap-profile-annotate.1.in

raw
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)