Debian Codegraph @

doc/SystemTap_Tapset_Reference/tapsets.tmpl

raw
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5 <book id="TapsetRef">
6 <bookinfo>
7 <title>SystemTap Tapset Reference Manual</title>
8 <!--starthere-->
9 <copyright>
10 <year>2008-2025</year> <!-- PRERELEASE -->
11 <holder>Red Hat, Inc. and others</holder>
12 </copyright>
13
14 <authorgroup>
15 <author>
16 <othername>SystemTap</othername>
17 <contrib>Hackers</contrib>
18 </author>
19 </authorgroup>
20
21
22 <legalnotice>
23 <para>
24 This documentation is free software; you can redistribute
25 it and/or modify it under the terms of the GNU General Public
26 License version 2 as published by the Free Software Foundation.
27 </para>
28
29 <para>
30 This program is distributed in the hope that it will be
31 useful, but WITHOUT ANY WARRANTY; without even the implied
32 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
33 See the GNU General Public License for more details.
34 </para>
35
36 <para>
37 You should have received a copy of the GNU General Public
38 License along with this program; if not, write to the Free
39 Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
40 Boston, MA 02110-1301 USA.
41 </para>
42
43 <para>
44 For more details see the file COPYING in the source
45 distribution of Linux.
46 </para>
47 </legalnotice>
48 </bookinfo>
49 <!-- pls dont remove marker comments, as they are used in publican conversion-->
50 <toc></toc>
51 <chapter id="introduction">
52 <title>Introduction</title>
53 <para>
54 SystemTap provides free software (GPL) infrastructure to simplify the
55 gathering of information about the running Linux system. This assists
56 diagnosis of a performance or functional problem. SystemTap eliminates the
57 need for the developer to go through the tedious and disruptive instrument,
58 recompile, install, and reboot sequence that may be otherwise required to
59 collect data.
60 </para>
61
62 <para>
63 SystemTap provides a simple command line interface and scripting language
64 for writing instrumentation for a live running kernel. The instrumentation
65 makes extensive use of the probe points and functions provided in the
66 <firstterm>tapset</firstterm> library. This document describes the various
67 probe points and functions.
68 </para>
69
70 <section id="format">
71 <title>Tapset Name Format</title>
72
73 <para>In this guide, tapset definitions appear in the following format:</para>
74
75 <screen>
76 name:return (parameters)
77 definition
78 </screen>
79
80 <para>
81 The <replaceable>return</replaceable> field specifies what data type the
82 tapset extracts and returns from the kernel during a probe (and thus,
83 returns). Tapsets use 2 data types for
84 <replaceable>return</replaceable>: <literal>long</literal> (tapset
85 extracts and returns an integer) and <literal>string</literal> (tapset
86 extracts and returns a string).
87 </para>
88
89 <para>
90 In some cases, tapsets do not have a <replaceable>return</replaceable>
91 value. This simply means that the tapset does not extract anything from
92 the kernel. This is common among asynchronous events such as timers,
93 exit functions, and print functions.
94 </para>
95 <!--
96 <varlistentry>
97 <term></term>
98 <listitem>
99 <para></para>
100 </listitem>
101 </varlistentry>
102 -->
103
104 </section>
105
106 </chapter>
107 <!--endhere-->
108 <!--markerforxi-->
109 <!-- pls dont remove marker comments, as they are used in publican conversion-->
110 <chapter id="context_stp">
111 <title>Context Functions</title>
112 <para>
113 The context functions provide additional information about where
114 an event occurred.
115 These functions can provide information such as a backtrace to
116 where the event occurred
117 and the current register values for the processor.
118 </para>
119 !Itapset/context.stp
120 !Itapset/linux/context.stp
121 !Itapset/linux/context-envvar.stp
122 !Itapset/linux/context-symbols.stp
123 !Itapset/linux/ucontext.stp
124 !Itapset/linux/ucontext-symbols.stp
125 !Itapset/linux/context-unwind.stp
126 !Itapset/linux/context-caller.stp
127 !Itapset/linux/ucontext-unwind.stp
128 !Itapset/linux/task.stp
129 !Itapset/linux/task_ancestry.stp
130 !Itapset/pn.stp
131 !Itapset/linux/pstrace.stp
132 !Itapset/registers.stp
133 </chapter>
134
135 <chapter id="timestamp_stp">
136 <title>Timestamp Functions</title>
137 <para>
138 Each timestamp function returns a value to indicate when
139 a function is executed.
140 These returned values can then be used to indicate
141 when an event occurred, provide an ordering for events, or compute
142 the amount of time elapsed between two time stamps.
143 </para>
144 !Itapset/linux/timestamp.stp
145 !Itapset/linux/timestamp_gtod.stp
146 !Itapset/linux/timestamp_monotonic.stp
147 !Itapset/stopwatch.stp
148 </chapter>
149
150 <chapter id="ctime.stp">
151 <title>Time utility functions</title>
152 <para>
153 Utility functions to turn seconds since the epoch (as returned by
154 the timestamp function gettimeofday_s()) into a human readable
155 date/time strings.
156 </para>
157 !Itapset/linux/ctime.stp
158 !Itapset/linux/tzinfo.stp
159 !Itapset/tzinfo.stp
160 </chapter>
161
162
163 <chapter id="system.stp">
164 <title>Shell command functions</title>
165 <para>
166 Utility functions to enqueue shell commands.
167 </para>
168 !Itapset/system.stp
169 </chapter>
170
171 <chapter id="memory_stp">
172 <title>Memory Tapset</title>
173 <para>
174 This family of probe points is used to probe memory-related events
175 or query the memory usage of the current process.
176 It contains the following probe points:
177 </para>
178 !Itapset/linux/memory.stp
179 !Itapset/linux/proc_mem.stp
180 </chapter>
181
182 <chapter id="task_time_stp">
183 <title>Task Time Tapset</title>
184 <para>
185 This tapset defines utility functions to query time related
186 properties of the current tasks, translate those in miliseconds
187 and human readable strings.
188 </para>
189 !Itapset/linux/task_time.stp
190 </chapter>
191
192 <chapter id="sched.stp">
193 <title>Scheduler Tapset</title>
194 <para>
195 This family of probe points is used to probe the task scheduler activities.
196 It contains the following probe points:
197 </para>
198 !Itapset/linux/scheduler.stp
199 </chapter>
200
201 <chapter id="iosched.stp">
202 <title>IO Scheduler and block IO Tapset</title>
203 <para>
204 This family of probe points is used to probe block IO layer and IO scheduler activities.
205 It contains the following probe points:
206 </para>
207 !Itapset/linux/ioscheduler.stp
208 !Itapset/linux/ioblock.stp
209 </chapter>
210
211 <chapter id="scsi.stp">
212 <title>SCSI Tapset</title>
213 <para>
214 This family of probe points is used to probe SCSI activities.
215 It contains the following probe points:
216 </para>
217 !Itapset/linux/scsi.stp
218 </chapter>
219
220 <chapter id="tty.stp">
221 <title>TTY Tapset</title>
222 <para>
223 This family of probe points is used to probe TTY (Teletype) activities.
224 It contains the following probe points:
225 </para>
226 !Itapset/linux/tty.stp
227 </chapter>
228
229 <chapter id="irq.stp">
230 <title>Interrupt Request (IRQ) Tapset</title>
231 <para>
232 This family of probe points is used to probe interrupt request
233 (IRQ) activities.
234 It contains the following probe points:
235 </para>
236 !Itapset/linux/irq.stp
237 </chapter>
238
239 <chapter id="networking.stp">
240 <title>Networking Tapset</title>
241 <para>
242 This family of probe points is used to probe the activities of
243 the network device and protocol layers.
244 </para>
245 !Itapset/linux/networking.stp
246 !Itapset/linux/tcp.stp
247 !Itapset/linux/udp.stp
248 !Itapset/linux/ip.stp
249 !Itapset/linux/inet.stp
250 !Itapset/linux/rpc.stp
251 !Itapset/linux/netfilter.stp
252 </chapter>
253
254 <chapter id="socket.stp">
255 <title>Socket Tapset</title>
256 <para>
257 This family of probe points is used to probe socket activities.
258 It contains the following probe points:
259 </para>
260 !Itapset/linux/socket.stp
261 !Itapset/linux/inet_sock.stp
262 </chapter>
263 <chapter id="snmp.stp">
264 <title>SNMP Information Tapset</title>
265 <para>
266 This family of probe points is used to probe socket activities to
267 provide SNMP type information. It contains the following functions
268 and probe points:
269 </para>
270 !Itapset/linux/ipmib.stp
271 !Itapset/linux/ipmib-filter-default.stp
272 !Itapset/linux/tcpmib.stp
273 !Itapset/linux/tcpmib-filter-default.stp
274 !Itapset/linux/linuxmib.stp
275 !Itapset/linux/linuxmib-filter-default.stp
276 </chapter>
277 <chapter id="kprocess.stp">
278 <title>Kernel Process Tapset</title>
279 <para>
280 This family of probe points is used to probe process-related activities.
281 It contains the following probe points:
282 </para>
283 !Itapset/linux/kprocess.stp
284 !Itapset/linux/target_set.stp
285 !Itapset/linux/loadavg.stp
286 </chapter>
287 <chapter id="signal.stp">
288 <title>Signal Tapset</title>
289 <para>
290 This family of probe points is used to probe signal activities.
291 It contains the following probe points:
292 </para>
293 !Itapset/linux/signal.stp
294 </chapter>
295 <chapter id="errno.stp">
296 <title>Errno Tapset</title>
297 <para>
298 This set of functions is used to handle errno number values.
299 It contains the following functions:
300 </para>
301 !Itapset/errno.stp
302 </chapter>
303 <chapter id="rlimit.stp">
304 <title>RLIMIT Tapset</title>
305 <para>
306 This set of functions is used to handle string which defines resource limits (RLIMIT_*) and returns
307 corresponding number of resource limit.
308 It contains the following functions:
309 </para>
310 !Itapset/linux/rlimit.stp
311 </chapter>
312 <chapter id="dev.stp">
313 <title>Device Tapset</title>
314 <para>
315 This set of functions is used to handle kernel and userspace device numbers.
316 It contains the following functions:
317 </para>
318 !Itapset/linux/dev.stp
319 </chapter>
320 <chapter id="dentry.stp">
321 <title>Directory-entry (dentry) Tapset</title>
322 <para>
323 This family of functions is used to map kernel VFS
324 directory entry pointers to file or full path names.
325 </para>
326 !Itapset/linux/dentry.stp
327 </chapter>
328 <chapter id="logging.stp">
329 <title>Logging Tapset</title>
330 <para>
331 This family of functions is used to send simple
332 message strings to various destinations.
333 </para>
334 !Itapset/logging.stp
335 !Itapset/linux/logging.stp
336 </chapter>
337 <chapter id="queue_stats.stp">
338 <title>Queue Statistics Tapset</title>
339 <para>
340 This family of functions is used to track performance of queuing systems.
341 </para>
342 !Itapset/queue_stats.stp
343 </chapter>
344 <chapter id="random.stp">
345 <title>Random functions Tapset</title>
346 <para>
347 These functions deal with random number generation.
348 </para>
349 !Itapset/random.stp
350 </chapter>
351 <chapter id="conversions.stp">
352 <title>String and data retrieving functions Tapset</title>
353 <para>
354 Functions to retrieve strings and other primitive types from
355 the kernel or a user space programs based on addresses. All
356 strings are of a maximum length given by MAXSTRINGLEN.
357 </para>
358 !Itapset/linux/conversions.stp
359 !Itapset/linux/atomic.stp
360 !Itapset/uconversions.stp
361 </chapter>
362
363 <chapter id="conversions-guru.stp">
364 <title>String and data writing functions Tapset</title>
365 <para>
366 The SystemTap guru mode can be used to test error handling
367 in kernel code by simulating faults. The functions in the
368 this tapset provide
369 standard methods of writing to primitive types in the kernel's
370 memory. All the functions in this tapset require the use of
371 guru mode (<command>-g</command>).
372 </para>
373 !Itapset/linux/conversions-guru.stp
374 !Itapset/uconversions-guru.stp
375 </chapter>
376
377 <chapter id="guru-delay.stp">
378 <title>Guru tapsets</title>
379 <para>
380 Functions to deliberately interfere with the system's behavior, in
381 order to inject faults or improve observability.
382 All the functions in this tapset require the use of
383 guru mode (<command>-g</command>).
384 </para>
385 !Itapset/linux/guru-delay.stp
386 !Itapset/linux/panic.stp
387 !Itapset/linux/guru-signal.stp
388 </chapter>
389
390 <chapter id="string.stp">
391 <title>A collection of standard string functions</title>
392 <para>
393 Functions to get the length, a substring, getting at individual
394 characters, string seaching, escaping, tokenizing, and converting
395 strings to longs.
396 </para>
397 !Itapset/string.stp
398 !Itapset/tokenize.stp
399 !Itapset/regex.stp
400 </chapter>
401 <chapter id="ansi.stp">
402 <title>Utility functions for using ansi control chars in logs</title>
403 <para>
404 Utility functions for logging using ansi control characters. This
405 lets you manipulate the cursor position and character color output
406 and attributes of log messages.
407 </para>
408 !Itapset/ansi.stp
409 !Itapset/indent.stp
410 </chapter>
411
412 <chapter id="stap_staticmarkers.stp">
413 <title>SystemTap Translator Tapset</title>
414 <para>
415 This family of user-space probe points is used to probe the operation of
416 the SystemTap translator (<command>stap</command>) and run command
417 (<command>staprun</command>).
418 The tapset includes probes to watch the various phases of SystemTap
419 and SystemTap's management of instrumentation cache.
420 It contains the following probe points:
421 </para>
422 !Itapset/stap_staticmarkers.stp
423 </chapter>
424
425 <chapter id="nfsd.stp">
426 <title>Network File Storage Tapsets</title>
427 <para>
428 This family of probe points is used to probe network file storage
429 functions and operations.
430 </para>
431 !Itapset/linux/nfs_proc.stp
432 !Itapset/linux/nfs.stp
433 !Itapset/linux/nfsd.stp
434 !Itapset/linux/nfsderrno.stp
435 </chapter>
436
437 <chapter id="speculation.stp">
438 <title>Speculation</title>
439 <para>
440 This family of functions provides the ability to speculative record
441 information and then at a later point in the SystemTap script either
442 commit the information or discard it.
443 </para>
444 !Itapset/speculative.stp
445 </chapter>
446
447 <chapter id="json.stp">
448 <title>JSON Tapset</title>
449 <para>
450 This family of probe points, functions, and macros is used to
451 output data in JSON format.
452 It contains the following probe points, functions, and macros:
453 </para>
454 !Itapset/linux/json.stp
455 !Itapset/linux/json.stpm
456 </chapter>
457
458 <chapter id="switchfile.stp">
459 <title>Output file switching Tapset</title>
460 <para>
461 Utility function to allow switching of output files.
462 </para>
463 !Itapset/switchfile.stp
464 </chapter>
465
466 <chapter id="floatingpoint.stp">
467 <title>Floating point processing Tapset</title>
468 <para>
469 Utility functions to extract, convert, and perform arithmetic
470 on IEEE-754 doubles.
471 </para>
472 !Itapset/floatingpoint.stp
473 </chapter>
474
475 <chapter id="syscall_any.stp">
476 <title>Syscall Any Tapset</title>
477 <para>
478 This family of probe points is designed to provide low cost
479 instrumentation for cases where only the syscall name (or number)
480 and return value are required and there is no need for the detailed
481 syscall argument values. They are restricted versions of
482 syscall.* and syscall.*.return.
483 </para>
484 !Itapset/linux/syscall_any.stp
485 </chapter>
486
487 <chapter id="livepatch.stp">
488 <title>CVE Livepatching Tapset</title>
489 <para>
490 Utility functions and control variables which can be used to create
491 standardized CVE patches. The globals are cve_notify_p (non-zero if the
492 patch should be verbose), cve_fix_p (non-zero if the fix should be applied),
493 cve_trace_p (non-zero if only a trace should be run), cve_enabled_p (non-zero
494 if the patch should be enabled). The controls can be changed in
495 /proc/systemtap/MODULE_NAME/* and the recorded prometheus metrics can be
496 viewed in the same directory.
497 </para>
498 !Itapset/livepatch.stp
499 </chapter>
500
501 !Syscalls
502
503 </book>