Debian Codegraph @

man/stapprobes.3stap

raw
1 .\" t
2 .TH STAPPROBES 3stap
3 .SH NAME
4 stapprobes \- systemtap probe points
5
6 .\" macros
7 .de SAMPLE
8
9 .nr oldin \\n(.i
10 .br
11 .RS
12 .nf
13 .nh
14 ..
15 .de ESAMPLE
16 .hy
17 .fi
18 .RE
19 .in \\n[oldin]u
20
21 ..
22
23 .SH DESCRIPTION
24 The following sections enumerate the variety of probe points supported
25 by the systemtap translator, and some of the additional aliases defined by
26 standard tapset scripts. Many are individually documented in the
27 .IR 3stap
28 manual section, with the
29 .IR probe::
30 prefix.
31
32 .SH SYNTAX
33
34 .PP
35 .SAMPLE
36 .BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " }
37 .ESAMPLE
38 .PP
39 A probe declaration may list multiple comma-separated probe points in
40 order to attach a handler to all of the named events. Normally, the
41 handler statements are run whenever any of events occur. Depending on
42 the type of probe point, the handler statements may refer to context
43 variables (denoted with a dollar-sign prefix like $foo) to read or
44 write state. This may include function parameters for function
45 probes, or local variables for statement probes.
46 .PP
47 The syntax of a single probe point is a general dotted-symbol
48 sequence. This allows a breakdown of the event namespace into parts,
49 somewhat like the Domain Name System does on the Internet. Each
50 component identifier may be parametrized by a string or number
51 literal, with a syntax like a function call. A component may include
52 a "*" character, to expand to a set of matching probe points. It may
53 also include "**" to match multiple sequential components at once.
54 Probe aliases likewise expand to other probe points.
55 .PP
56 Probe aliases can be given on their own, or with a suffix. The suffix
57 attaches to the underlying probe point that the alias is expanded
58 to. For example,
59 .SAMPLE
60 syscall.read.return.maxactive(10)
61 .ESAMPLE
62 expands to
63 .SAMPLE
64 kernel.function("sys_read").return.maxactive(10)
65 .ESAMPLE
66 with the component
67 .IR maxactive(10)
68 being recognized as a suffix.
69 .PP
70 Normally, each and every probe point resulting from wildcard- and
71 alias-expansion must be resolved to some low-level system
72 instrumentation facility (e.g., a kprobe address, marker, or a timer
73 configuration), otherwise the elaboration phase will fail.
74 .PP
75 However, a probe point may be followed by a "?" character, to indicate
76 that it is optional, and that no error should result if it fails to
77 resolve. Optionalness passes down through all levels of
78 alias/wildcard expansion. Alternately, a probe point may be followed
79 by a "!" character, to indicate that it is both optional and
80 sufficient. (Think vaguely of the Prolog cut operator.) If it does
81 resolve, then no further probe points in the same comma-separated list
82 will be resolved. Therefore, the "!" sufficiency mark only makes
83 sense in a list of probe point alternatives.
84 .PP
85 Additionally, a probe point may be followed by a "if (expr)" statement, in
86 order to enable/disable the probe point on-the-fly. With the "if" statement,
87 if the "expr" is false when the probe point is hit, the whole probe body
88 including alias's body is skipped. The condition is stacked up through
89 all levels of alias/wildcard expansion. So the final condition becomes
90 the logical-and of conditions of all expanded alias/wildcard. The expressions
91 are necessarily restricted to global variables.
92 .PP
93 These are all
94 .B syntactically
95 valid probe points. (They are generally
96 .B semantically
97 invalid, depending on the contents of the tapsets, and the versions of
98 kernel/user software installed.)
99
100 .SAMPLE
101 kernel.function("foo").return
102 process("/bin/vi").statement(0x2222)
103 end
104 syscall.*
105 syscall.*.return.maxactive(10)
106 syscall.{open,close}
107 sys**open
108 kernel.function("no_such_function") ?
109 module("awol").function("no_such_function") !
110 signal.*? if (switch)
111 kprobe.function("foo")
112 .ESAMPLE
113
114 Probes may be broadly classified into "synchronous" and
115 "asynchronous". A "synchronous" event is deemed to occur when any
116 processor executes an instruction matched by the specification. This
117 gives these probes a reference point (instruction address) from which
118 more contextual data may be available. Other families of probe points
119 refer to "asynchronous" events such as timers/counters rolling over,
120 where there is no fixed reference point that is related. Each probe
121 point specification may match multiple locations (for example, using
122 wildcards or aliases), and all them are then probed. A probe
123 declaration may also contain several comma-separated specifications,
124 all of which are probed.
125
126 Brace expansion is a mechanism which allows a list of probe points to be
127 generated. It is very similar to shell expansion. A component may be surrounded
128 by a pair of curly braces to indicate that the comma-separated sequence of
129 one or more subcomponents will each constitute a new probe point. The braces
130 may be arbitrarily nested. The ordering of expanded results is based on
131 product order.
132
133 The question mark (?), exclamation mark (!) indicators and probe point conditions
134 may not be placed in any expansions that are before the last component.
135
136 The following is an example of brace expansion.
137
138 .SAMPLE
139 syscall.{write,read}
140 # Expands to
141 syscall.write, syscall.read
142
143 {kernel,module("nfs")}.function("nfs*")!
144 # Expands to
145 kernel.function("nfs*")!, module("nfs").function("nfs*")!
146 .ESAMPLE
147
148 .SH DWARF DEBUGINFO
149
150 Resolving some probe points requires DWARF debuginfo or "debug
151 symbols" for the \fIspecific program\fR being instrumented. For some others,
152 DWARF is automatically synthesized on the fly from source code header
153 files. For others, it is not needed at all. Since a systemtap script
154 may use any mixture of probe points together, the union of their DWARF
155 requirements has to be met on the computer where script compilation
156 occurs. (See the \fI\-\-use\-server\fR option and the \fBstap-server\
157 (8)\fR man page for information about the remote compilation facility,
158 which allows these requirements to be met on a different machine.)
159 .PP
160 The following point lists many of the available probe point families,
161 to classify them with respect to their need for DWARF debuginfo for
162 the specific program for that probe point.
163
164 .TS
165 l l l.
166 \fBDWARF NON-DWARF SYMBOL-TABLE\fP
167
168 kernel.function, .statement kernel.mark kernel.function\fI*\fP
169 module.function, .statement process.mark, process.plt module.function\fI*\fP
170 process.function, .statement begin, end, error, never process.function\fI*\fP
171 process.mark\fI*\fP timer
172 \.function.callee perf
173 python2, python3 procfs
174 debuginfod kernel.statement.absolute
175 kernel.data
176 \fBAUTO-GENERATED-DWARF\fP kprobe.function
177 kernel.trace process.statement.absolute
178 process.begin, .end
179 netfilter
180 java
181 .TE
182
183 .PP
184 The probe types marked with \fI*\fP asterisks mark fallbacks, where
185 systemtap can sometimes infer subset or substitute information. In
186 general, the more symbolic / debugging information available, the
187 higher quality probing will be available.
188
189
190 .SH ON-THE-FLY ARMING
191
192 The following types of probe points may be armed/disarmed on-the-fly
193 to save overheads during uninteresting times. Arming conditions may
194 also be added to other types of probes, but will be treated as a
195 wrapping conditional and won't benefit from overhead savings.
196
197 .TS
198 l l.
199 \fBDISARMABLE exceptions\fP
200 kernel.function, kernel.statement
201 module.function, module.statement
202 process.*.function, process.*.statement
203 process.*.plt, process.*.mark
204 timer. timer.profile
205 java
206 .TE
207
208 .SH PROBE POINT FAMILIES
209
210 .SS BEGIN/END/ERROR
211
212 The probe points
213 .IR begin " and " end
214 are defined by the translator to refer to the time of session startup
215 and shutdown. All "begin" probe handlers are run, in some sequence,
216 during the startup of the session. All global variables will have
217 been initialized prior to this point. All "end" probes are run, in
218 some sequence, during the
219 .I normal
220 shutdown of a session, such as in the aftermath of an
221 .I exit ()
222 function call, or an interruption from the user. In the case of an
223 error-triggered shutdown, "end" probes are not run. There are no
224 target variables available in either context.
225 .PP
226 If the order of execution among "begin" or "end" probes is significant,
227 then an optional sequence number may be provided:
228
229 .SAMPLE
230 begin(N)
231 end(N)
232 .ESAMPLE
233
234 The number N may be positive or negative. The probe handlers are run in
235 increasing order, and the order between handlers with the same sequence
236 number is unspecified. When "begin" or "end" are given without a
237 sequence, they are effectively sequence zero.
238
239 The
240 .IR error
241 probe point is similar to the
242 .IR end
243 probe, except that each such probe handler run when the session ends
244 after errors have occurred. In such cases, "end" probes are skipped,
245 but each "error" probe is still attempted. This kind of probe can be
246 used to clean up or emit a "final gasp". It may also be numerically
247 parametrized to set a sequence.
248
249 .SS NEVER
250 The probe point
251 .IR never
252 is specially defined by the translator to mean "never". Its probe
253 handler is never run, though its statements are analyzed for symbol /
254 type correctness as usual. This probe point may be useful in
255 conjunction with optional probes.
256
257 .SS SYSCALL and ND_SYSCALL
258
259 The
260 .IR syscall.* " and " nd_syscall.*
261 aliases define several hundred probes, too many to
262 detail here. They are of the general form:
263
264 .SAMPLE
265 syscall.NAME
266 .br
267 nd_syscall.NAME
268 .br
269 syscall.NAME.return
270 .br
271 nd_syscall.NAME.return
272 .ESAMPLE
273
274 Generally, a pair of probes are defined for each normal system call as listed in the
275 .IR syscalls(2)
276 manual page, one for entry and one for return. Those system calls that never
277 return do not have a corresponding
278 .IR .return
279 probe. The nd_* family of probes are about the same, except it uses
280 .B non-DWARF
281 based searching mechanisms, which may result in a lower quality of symbolic
282 context data (parameters), and may miss some system calls. You may want to
283 try them first, in case kernel debugging information is not immediately available.
284 .PP
285 Each probe alias provides a variety of variables. Looking at the tapset source
286 code is the most reliable way. Generally, each variable listed in the standard
287 manual page is made available as a script-level variable, so
288 .IR syscall.open
289 exposes
290 .IR filename ", " flags ", and " mode .
291 In addition, a standard suite of variables is available at most aliases:
292 .TP
293 .IR argstr
294 A pretty-printed form of the entire argument list, without parentheses.
295 .TP
296 .IR name
297 The name of the system call.
298 .TP
299 .IR retval
300 For return probes, the raw numeric system-call result.
301 .TP
302 .IR retstr
303 For return probes, a pretty-printed string form of the system-call result.
304 .PP
305 As usual for probe aliases, these variables are all initialized once
306 from the underlying $context variables, so that later changes to
307 $context variables are not automatically reflected. Not all probe
308 aliases obey all of these general guidelines. Please report any
309 bothersome ones you encounter as a bug. Note that on some
310 kernel/userspace architecture combinations (e.g., 32-bit userspace on
311 64-bit kernel), the underlying $context variables may need explicit
312 sign extension / masking. When this is an issue, consider using the
313 tapset-provided variables instead of raw $context variables.
314 .PP
315 If debuginfo availability is a problem, you may try using the
316 non-DWARF syscall probe aliases instead. Use the
317 .IR nd_syscall.
318 prefix instead of
319 .IR syscall.
320 The same context variables are available, as far as possible.
321 .PP
322 .IR nd_syscall
323 probes on kernels that use syscall wrappers to pass arguments via pt_regs
324 (currently 4.17+ on x86_64 and 4.19+ on aarch64) support syscall argument
325 writing when guru mode is enabled. If a probe syscall parameter is modified
326 in the probe body then immediately before the probe exits the parameter's
327 current value will be written to pt_regs. This overwrites the previous value.
328 .IR nd_syscall
329 probes also include two parameters for each of the syscall's string parameters.
330 One holds a quoted version of the string passed to the syscall. The other holds
331 an unquoted version of the string intended to be used when modifying the parameter.
332 If the probe modifies the unquoted string variable then as the probe is about to
333 exit the contents of this variable will be written to the user space buffer passed
334 to the syscall. It is the user's responsibility to ensure that this buffer is large
335 enough to hold the modified string and that it is located in a writable memory
336 segment.
337
338 .SS TIMERS
339
340 There are two main types of timer probes: "jiffies" timer probes and
341 time interval timer probes.
342
343 Intervals defined by the standard kernel "jiffies" timer may be used
344 to trigger probe handlers asynchronously. Two probe point variants
345 are supported by the translator:
346
347 .SAMPLE
348 timer.jiffies(N)
349 timer.jiffies(N).randomize(M)
350 .ESAMPLE
351
352 The probe handler is run every N jiffies (a kernel-defined unit of
353 time, typically between 1 and 60 ms). If the "randomize" component is
354 given, a linearly distributed random value in the range [\-M..+M] is
355 added to N every time the handler is run. N is restricted to a
356 reasonable range (1 to around a million), and M is restricted to be
357 smaller than N. There are no target variables provided in either
358 context. It is possible for such probes to be run concurrently on
359 a multi-processor computer.
360 .PP
361 Alternatively, intervals may be specified in units of time.
362 There are two probe point variants similar to the jiffies timer:
363
364 .SAMPLE
365 timer.ms(N)
366 timer.ms(N).randomize(M)
367 .ESAMPLE
368
369 Here, N and M are specified in milliseconds, but the full options for units
370 are seconds (s/sec), milliseconds (ms/msec), microseconds (us/usec),
371 nanoseconds (ns/nsec), and hertz (hz). Randomization is not supported for
372 hertz timers.
373
374 The actual resolution of the timers depends on the target kernel. For
375 kernels prior to 2.6.17, timers are limited to jiffies resolution, so
376 intervals are rounded up to the nearest jiffies interval. After 2.6.17,
377 the implementation uses hrtimers for tighter precision, though the actual
378 resolution will be arch-dependent. In either case, if the "randomize"
379 component is given, then the random value will be added to the interval
380 before any rounding occurs.
381 .PP
382 Profiling timers are also available to provide probes that execute on
383 all CPUs at the rate of the system tick (CONFIG_HZ) or at a given
384 frequency (hz). On some kernels, this is a one-concurrent-user-only or
385 disabled facility, resulting in error \-16 (EBUSY) during probe
386 registration.
387
388 .SAMPLE
389 timer.profile.tick
390 timer.profile.freq.hz(N)
391 .ESAMPLE
392
393 Full context information of the interrupted process is available, making
394 this probe suitable for a time-based sampling profiler.
395 .PP
396 It is recommended to use the tapset probe
397 .IR timer.profile
398 rather than timer.profile.tick. This probe point behaves identically
399 to timer.profile.tick when the underlying functionality is available,
400 and falls back to using perf.sw.cpu_clock on some recent kernels which
401 lack the corresponding profile timer facility.
402 .PP
403 Profiling timers with specified frequencies are only accurate up to around
404 100 hz. You may need to provide a larger value to achieve the desired
405 rate.
406 .PP
407 Note that if a timer probe is set to fire at a very high rate
408 and if the probe body is complex, succeeding timer probes can get
409 skipped, since the time for them to run has already passed. Normally
410 systemtap reports missed probes, but it will not report these skipped
411 probes.
412
413 .SS DWARF
414
415 This family of probe points uses symbolic debugging information for
416 the target kernel/module/program, as may be found in unstripped
417 executables, or the separate
418 .I debuginfo
419 packages. They allow placement of probes logically into the execution
420 path of the target program, by specifying a set of points in the
421 source or object code. When a matching statement executes on any
422 processor, the probe handler is run in that context.
423 .PP
424 Probe points in the DWARF family can be identified by the target kernel
425 module (or user process), source file, line number, function name, or
426 some combination of these.
427 .PP
428 Here is a list of DWARF probe points currently supported:
429 .SAMPLE
430 kernel.function(PATTERN)
431 kernel.function(PATTERN).call
432 kernel.function(PATTERN).callee(PATTERN)
433 kernel.function(PATTERN).callee(PATTERN).return
434 kernel.function(PATTERN).callee(PATTERN).call
435 kernel.function(PATTERN).callees(DEPTH)
436 kernel.function(PATTERN).return
437 kernel.function(PATTERN).inline
438 kernel.function(PATTERN).label(LPATTERN)
439 module(MPATTERN).function(PATTERN)
440 module(MPATTERN).function(PATTERN).call
441 module(MPATTERN).function(PATTERN).callee(PATTERN)
442 module(MPATTERN).function(PATTERN).callee(PATTERN).return
443 module(MPATTERN).function(PATTERN).callee(PATTERN).call
444 module(MPATTERN).function(PATTERN).callees(DEPTH)
445 module(MPATTERN).function(PATTERN).return
446 module(MPATTERN).function(PATTERN).inline
447 module(MPATTERN).function(PATTERN).label(LPATTERN)
448 kernel.statement(PATTERN)
449 kernel.statement(PATTERN).nearest
450 kernel.statement(ADDRESS).absolute
451 module(MPATTERN).statement(PATTERN)
452 process("PATH").function("NAME")
453 process("PATH").statement("*@FILE.c:123")
454 process("PATH").library("PATH").function("NAME")
455 process("PATH").library("PATH").statement("*@FILE.c:123")
456 process("PATH").library("PATH").statement("*@FILE.c:123").nearest
457 process("PATH").function("*").return
458 process("PATH").function("myfun").label("foo")
459 process("PATH").function("foo").callee("bar")
460 process("PATH").function("foo").callee("bar").return
461 process("PATH").function("foo").callee("bar").call
462 process("PATH").function("foo").callees(DEPTH)
463 process(PID).function("NAME")
464 process(PID).function("myfun").label("foo")
465 process(PID).plt("NAME")
466 process(PID).plt("NAME").return
467 process(PID).statement("*@FILE.c:123")
468 process(PID).statement("*@FILE.c:123").nearest
469 process(PID).statement(ADDRESS).absolute
470 debuginfod.process("PATH").**
471 .ESAMPLE
472 (See the USER-SPACE section below for more information on the process
473 probes.)
474 .PP
475 The list above includes multiple variants and modifiers which provide
476 additional functionality or filters. They are:
477 .RS
478 .TP
479 \fB.function\fR
480 Places a probe near the beginning of the named function, so that
481 parameters are available as context variables.
482 .TP
483 \fB.return\fR
484 Places a probe at the moment \fBafter\fR the return from the named
485 function, so the return value is available as the "$return" context
486 variable.
487 .TP
488 \fB.inline\fR
489 Filters the results to include only instances of inlined functions. Note
490 that inlined functions do not have an identifiable return point, so
491 \fB.return\fR is not supported on \fB.inline\fR probes.
492 .TP
493 \fB.call\fR
494 Filters the results to include only non-inlined functions (the opposite
495 set of \fB.inline\fR)
496 .TP
497 \fB.exported\fR
498 Filters the results to include only exported functions.
499 .TP
500 \fB.statement\fR
501 Places a probe at the exact spot, exposing those local variables that
502 are visible there.
503 .TP
504 \fB.statement.nearest\fR
505 Places a probe at the nearest available line number for each line number
506 given in the statement.
507 .TP
508 \fB.callee\fR
509 Places a probe on the callee function given in the \fB.callee\fR
510 modifier, where the callee must be a function called by the target
511 function given in \fB.function\fR. The advantage of doing this over
512 directly probing the callee function is that this probe point is run
513 only when the callee is called from the target function (add the
514 -DSTAP_CALLEE_MATCHALL directive to override this when calling
515 \fBstap\fR(1)).
516
517 Note that only callees that can be statically determined are available.
518 For example, calls through function pointers are not available.
519 Additionally, calls to functions located in other objects (e.g.
520 libraries) are not available (instead use another probe point). This
521 feature will only work for code compiled with GCC 4.7+.
522 .TP
523 \fB.callees\fR
524 Shortcut for \fB.callee("*")\fR, which places a probe on all callees of
525 the function.
526 .TP
527 \fB.callees\fR(DEPTH)
528 Recursively places probes on callees. For example, \fB.callees(2)\fR
529 will probe both callees of the target function, as well as callees of
530 those callees. And \fB.callees(3)\fR goes one level deeper, etc...
531 A callee probe at depth N is only triggered when the N callers in the
532 callstack match those that were statically determined during analysis
533 (this also may be overridden using -DSTAP_CALLEE_MATCHALL).
534 .RE
535 .PP
536 In the above list of probe points, MPATTERN stands for a string literal
537 that aims to identify the loaded kernel module of interest. For in-tree
538 kernel modules, the name suffices (e.g. "btrfs"). The name may also
539 include the "*", "[]", and "?" wildcards to match multiple in-tree
540 modules. Out-of-tree modules are also supported by specifying the full
541 path to the ko file. Wildcards are not supported. The file must follow
542 the convention of being named <module_name>.ko (characters ',' and '-'
543 are replaced by '_').
544 .PP
545 LPATTERN stands for a source program label. It may also contain "*",
546 "[]", and "?" wildcards. PATTERN stands for a string literal that aims
547 to identify a point in the program. It is made up of three parts:
548 .IP \(bu 4
549 The first part is the name of a function, as would appear in the
550 .I nm
551 program's output. This part may use the "*" and "?" wildcarding
552 operators to match multiple names.
553 .IP \(bu 4
554 The second part is optional and begins with the "@" character.
555 It is followed by the path to the source file containing the function,
556 which may include a wildcard pattern, such as mm/slab*.
557 If it does not match as is, an implicit "*/" is optionally added
558 .I before
559 the pattern, so that a script need only name the last few components
560 of a possibly long source directory path.
561 .IP \(bu 4
562 Finally, the third part is optional if the file name part was given,
563 and identifies the line number in the source file preceded by a ":"
564 or a "+". The line number is assumed to be an
565 absolute line number if preceded by a ":", or relative to the
566 declaration line of the function if preceded by a "+".
567 All the lines in the function can be matched with ":*".
568 A range of lines x through y can be matched with ":x\-y". Ranges and
569 specific lines can be mixed using commas, e.g. ":x,y\-z".
570 .PP
571 As an alternative, PATTERN may be a numeric constant, indicating an
572 address. Such an address may be found from symbol tables of the
573 appropriate kernel / module object file. It is verified against
574 known statement code boundaries, and will be relocated for use at
575 run time.
576 .PP
577 In guru mode only, absolute kernel-space addresses may be specified with
578 the ".absolute" suffix. Such an address is considered already relocated,
579 as if it came from
580 .BR /proc/kallsyms ,
581 so it cannot be checked against statement/instruction boundaries.
582
583 .SS CONTEXT VARIABLES
584
585 .PP
586 Many of the source-level context variables, such as function parameters,
587 locals, globals visible in the compilation unit, may be visible to
588 probe handlers. They may refer to these variables by prefixing their
589 name with "$" within the scripts. In addition, a special syntax
590 allows limited traversal of structures, pointers, and arrays. More
591 syntax allows pretty-printing of individual variables or their groups.
592 See also
593 .BR @cast .
594 Note that variables may be inaccessible due to them being paged out,
595 or for a few other reasons. See also man
596 .IR error::fault (7stap).
597
598 .PP
599 Functions called from DWARF class probe points and from process.mark
600 probes may also refer to context variables.
601
602 .TP
603 $var
604 refers to an in-scope variable or thread local storage variable
605 "var". If it's an integer-like type,
606 it will be cast to a 64-bit int for systemtap script use. String-like
607 pointers (char *) may be copied to systemtap string values using the
608 .IR kernel_string " or " user_string
609 functions.
610 .TP
611 @var("varname")
612 an alternative syntax for
613 .IR $varname
614 .
615 .TP
616 @var("varname","module")
617 The global variable or global thread local storage variable
618 in scope of the given module already loaded into
619 the current probed process. Useful to get an exported variable in a
620 shared library loaded into the process being probed, or a global
621 variable in a process while a shared library probe is being executed.
622 For user-space modules only. For example:
623 .IR @var("_r_debug","/lib/ld-linux.so.2")
624 .
625 .TP
626 @var("varname@src/file.c")
627 refers to the global (either file local or external) variable
628 .IR varname
629 defined when the file
630 .IR src/file.c
631 was compiled. The CU in which the variable is resolved is the first CU
632 in the module of the probe point which matches the given file name at
633 the end and has the shortest file name path (e.g. given
634 .IR @var("foo@bar/baz.c")
635 and CUs with file name paths
636 .IR src/sub/module/bar/baz.c
637 and
638 .IR src/bar/baz.c
639 the second CU will be chosen to resolve the (file) global variable
640 .IR foo
641 .
642
643 .TP
644 @var("varname@src/file.c","module")
645 The global variable in scope of the given CU, defined in the given module,
646 even if the variable is static (so the name is not unique without the CU name).
647
648 .TP
649 $var\->field traversal via a structure's or a pointer's field. This
650 generalized indirection operator may be repeated to follow more
651 levels. Note that the
652 .IR .
653 operator is not used for plain structure
654 members, only
655 .IR \->
656 for both purposes. (This is because "." is reserved for string
657 concatenation.) Also note that for direct dereferencing of $var
658 pointer {kernel,user}_{char,int,...}($var) should be used. (Refer to
659 stapfuncs(5) for more details.)
660 .TP
661 $return
662 is available in return probes only for functions that are declared
663 with a return value, which can be determined using @defined($return).
664 .TP
665 $var[N]
666 indexes into an array. The index given with a literal number or even
667 an arbitrary numeric expression.
668 .PP
669 A number of operators exist for such basic context variable expressions:
670 .TP
671 $$vars
672 expands to a character string that is equivalent to
673 .SAMPLE
674 sprintf("parm1=%x ... parmN=%x var1=%x ... varN=%x",
675 parm1, ..., parmN, var1, ..., varN)
676 .ESAMPLE
677 for each variable in scope at the probe point. Some values may be
678 printed as
679 .IR =?
680 if their run-time location cannot be found.
681 .TP
682 $$locals
683 expands to a subset of $$vars for only local variables.
684 .TP
685 $$parms
686 expands to a subset of $$vars for only function parameters.
687 .TP
688 $$return
689 is available in return probes only. It expands to a string that
690 is equivalent to sprintf("return=%x", $return)
691 if the probed function has a return value, or else an empty string.
692 .TP
693 & $EXPR
694 expands to the address of the given context variable expression, if it
695 is addressable.
696 .TP
697 @defined($EXPR)
698 expands to 1 or 0 iff the given context variable expression is resolvable,
699 for use in conditionals such as
700 .SAMPLE
701 @defined($foo\->bar) ? $foo\->bar : 0
702 .ESAMPLE
703 Use full $context variables or @cast() expressions in @define parameters
704 for unambiguous processing. The TYPECAST script-level variable
705 facility is incompletely supported. Simplify the parameters by reducing
706 nesting or indirection, if encountering "Collapsing unresolved @define to ..."
707 warnings.
708 .TP
709 @probewrite($VAR)
710 see the PROBES section of \fIstap\fR(1).
711 .TP
712 $EXPR$
713 expands to a string with all of $EXPR's members, equivalent to
714 .SAMPLE
715 sprintf("{.a=%i, .b=%u, .c={...}, .d=[...]}",
716 $EXPR\->a, $EXPR\->b)
717 .ESAMPLE
718 .TP
719 $EXPR$$
720 expands to a string with all of $var's members and submembers, equivalent to
721 .SAMPLE
722 sprintf("{.a=%i, .b=%u, .c={.x=%p, .y=%c}, .d=[%i, ...]}",
723 $EXPR\->a, $EXPR\->b, $EXPR\->c\->x, $EXPR\->c\->y, $EXPR\->d[0])
724 .ESAMPLE
725 .TP
726 @errno
727 expands to the last value the C library global variable errno was set to.
728
729 .SS MORE ON RETURN PROBES
730
731 .PP
732 For the kernel ".return" probes, only a certain fixed number of
733 returns may be outstanding. The default is a relatively small number,
734 on the order of a few times the number of physical CPUs. If many
735 different threads concurrently call the same blocking function, such
736 as futex(2) or read(2), this limit could be exceeded, and skipped
737 "kretprobes" would be reported by "stap \-t". To work around this,
738 specify a
739 .SAMPLE
740 probe FOO.return.maxactive(NNN)
741 .ESAMPLE
742 suffix, with a large enough NNN to cover all expected concurrently blocked
743 threads. Alternately, use the
744 .SAMPLE
745 stap \-DKRETACTIVE=NNNN
746 .ESAMPLE
747 stap command line macro setting to override the default for all
748 ".return" probes.
749
750 .PP
751 For ".return" probes, context variables other than the "$return" may
752 be accessible, as a convenience for a script programmer wishing to
753 access function parameters. These values are \fBsnapshots\fP
754 taken at the time of function entry. (Local variables within the
755 function are \fBnot\fP generally accessible, since those variables did
756 not exist in allocated/initialized form at the snapshot moment.)
757 These entry-snapshot variables should be accessed via
758 .IR @entry($var) .
759 .PP
760 In addition, arbitrary entry-time expressions can also be saved for
761 ".return" probes using the
762 .IR @entry(expr)
763 operator. For example, one can compute the elapsed time of a function:
764 .SAMPLE
765 probe kernel.function("do_filp_open").return {
766 println( get_timeofday_us() \- @entry(get_timeofday_us()) )
767 }
768 .ESAMPLE
769
770 .PP
771 The following table summarizes how values related to a function
772 parameter context variable, a pointer named \fBaddr\fP, may be
773 accessed from a
774 .IR .return
775 probe.
776 .\" summarized from http://sourceware.org/ml/systemtap/2012-q1/msg00025.html
777 .TS
778 l l l.
779 \fBat-entry value past-exit value\fP
780
781 $addr \fInot available\fP
782 $addr->x->y @cast(@entry($addr),"struct zz")->x->y
783 $addr[0] {kernel,user}_{char,int,...}(& $addr[0])
784 .TE
785
786
787 .SS DWARFLESS
788 In absence of debugging information, entry & exit points of kernel & module
789 functions can be probed using the "kprobe" family of probes.
790 However, these do not permit looking up the arguments / local variables
791 of the function.
792 Following constructs are supported :
793 .SAMPLE
794 kprobe.function(FUNCTION)
795 kprobe.function(FUNCTION).call
796 kprobe.function(FUNCTION).return
797 kprobe.module(NAME).function(FUNCTION)
798 kprobe.module(NAME).function(FUNCTION).call
799 kprobe.module(NAME).function(FUNCTION).return
800 kprobe.statement(ADDRESS).absolute
801 .ESAMPLE
802 .PP
803 Probes of type
804 .B function
805 are recommended for kernel functions, whereas probes of type
806 .B module
807 are recommended for probing functions of the specified module.
808 In case the absolute address of a kernel or module function is known,
809 .B statement
810 probes can be utilized.
811 .PP
812 Note that
813 .I FUNCTION
814 and
815 .I MODULE
816 names
817 .B must not
818 contain wildcards, or the probe will not be registered.
819 Also, statement probes must be run under guru-mode only.
820
821
822 .SS USER-SPACE
823 Support for user-space probing is available for kernels that are
824 configured with the utrace extensions, or have the uprobes facility in
825 linux 3.5. (Various kernel build configuration options need to be
826 enabled; systemtap will advise if these are missing.)
827
828 .PP
829 There are several forms. First, a non-symbolic probe point:
830 .SAMPLE
831 process(PID).statement(ADDRESS).absolute
832 .ESAMPLE
833 is analogous to
834 .IR
835 kernel.statement(ADDRESS).absolute
836 in that both use raw (unverified) virtual addresses and provide
837 no $variables. The target PID parameter must identify a running
838 process, and ADDRESS should identify a valid instruction address.
839 All threads of that process will be probed.
840 .PP
841 Second, non-symbolic user-kernel interface events handled by
842 utrace may be probed:
843 .SAMPLE
844 process(PID).begin
845 process("FULLPATH").begin
846 process.begin
847 process(PID).thread.begin
848 process("FULLPATH").thread.begin
849 process.thread.begin
850 process(PID).end
851 process("FULLPATH").end
852 process.end
853 process(PID).thread.end
854 process("FULLPATH").thread.end
855 process.thread.end
856 process(PID).syscall
857 process("FULLPATH").syscall
858 process.syscall
859 process(PID).syscall.return
860 process("FULLPATH").syscall.return
861 process.syscall.return
862 .ESAMPLE
863
864 .PP
865 A
866 .B process.begin
867 probe gets called when new process described by PID or FULLPATH gets created.
868 In addition, it is called once from the context of each preexisting process,
869 at systemtap script startup. This is useful to track live processes.
870 A
871 .B process.thread.begin
872 probe gets called when a new thread described by PID or FULLPATH gets created.
873 A
874 .B process.end
875 probe gets called when process described by PID or FULLPATH dies.
876 A
877 .B process.thread.end
878 probe gets called when a thread described by PID or FULLPATH dies.
879 A
880 .B process.syscall
881 probe gets called when a thread described by PID or FULLPATH makes a
882 system call. The system call number is available in the
883 .BR $syscall
884 context variable, and the first 6 arguments of the system call
885 are available in the
886 .BR $argN
887 (ex. $arg1, $arg2, ...) context variable.
888 A
889 .B process.syscall.return
890 probe gets called when a thread described by PID or FULLPATH returns from a
891 system call. The system call number is available in the
892 .BR $syscall
893 context variable, and the return value of the system call is available
894 in the
895 .BR $return
896 context variable.
897 A
898
899 .PP
900 If a process probe is specified without a PID or FULLPATH, all user
901 threads will be probed. However, if systemtap was invoked with the
902 .IR \-c " or " \-x
903 options, then process probes are restricted to the process
904 hierarchy associated with the target process. If a process probe is
905 unspecified (i.e. without a PID or FULLPATH), but with the
906 .IR \-c "
907 option, the PATH of the
908 .IR \-c "
909 cmd will be heuristically filled into the process PATH. In that case,
910 only command parameters are allowed in the \fI-c\fR command (i.e. no
911 command substitution allowed and no occurrences of any of these
912 characters: '|&;<>(){}').
913
914 .PP
915 Third, symbolic static instrumentation compiled into programs and
916 shared libraries may be
917 probed:
918 .SAMPLE
919 process("PATH").mark("LABEL")
920 process("PATH").provider("PROVIDER").mark("LABEL")
921 process(PID).mark("LABEL")
922 process(PID).provider("PROVIDER").mark("LABEL")
923 .ESAMPLE
924 .PP
925 A
926 .B .mark
927 probe gets called via a static probe which is defined in the
928 application by STAP_PROBE1(PROVIDER,LABEL,arg1), which are macros defined in
929 .BR sys/sdt.h .
930 The PROVIDER is an arbitrary application identifier, LABEL is the
931 marker site identifier, and arg1 is the integer-typed argument.
932 STAP_PROBE1 is used for probes with 1 argument, STAP_PROBE2 is used
933 for probes with 2 arguments, and so on. The arguments of the probe
934 are available in the context variables $arg1, $arg2, ... An
935 alternative to using the STAP_PROBE macros is to use the dtrace script
936 to create custom macros. Additionally, the variables $$name and
937 $$provider are available as parts of the probe point name. The
938 .B sys/sdt.h
939 macro names DTRACE_PROBE* are available as aliases for STAP_PROBE*.
940
941 .PP
942 Finally, full symbolic source-level probes in user-space programs and
943 shared libraries are supported. These are exactly analogous to the
944 symbolic DWARF-based kernel/module probes described above. They
945 expose the same sorts of context $variables for function parameters,
946 local variables, and so on.
947 .SAMPLE
948 process("PATH").function("NAME")
949 process("PATH").statement("*@FILE.c:123")
950 process("PATH").plt("NAME")
951 process("PATH").library("PATH").plt("NAME")
952 process("PATH").library("PATH").function("NAME")
953 process("PATH").library("PATH").statement("*@FILE.c:123")
954 process("PATH").function("*").return
955 process("PATH").function("myfun").label("foo")
956 process("PATH").function("foo").callee("bar")
957 process("PATH").plt("NAME").return
958 debuginfod.process("PATH").**
959 process(PID).function("NAME")
960 process(PID).statement("*@FILE.c:123")
961 process(PID).plt("NAME")
962 .ESAMPLE
963
964 .PP
965 Note that for all process probes,
966 .I PATH
967 names refer to executables that are searched the same way shells do: relative
968 to the working directory if they contain a "/" character, otherwise in
969 .BR $PATH .
970 If PATH names refer to scripts, the actual interpreters (specified in the
971 script in the first line after the #! characters) are probed.
972 In the debuginfod probe family
973 .I PATH
974 names likewise refer to executables, but are searched for in the currently
975 defined
976 .BR $DEBUGINFOD_URLS .
977
978
979 .PP
980 Tapset process probes placed in the special directory
981 $prefix/share/systemtap/tapset/PATH/ with relative paths will have their
982 process parameter prefixed with the location of the tapset. For example,
983
984 .SAMPLE
985 process("foo").function("NAME")
986 .ESAMPLE
987 .PP
988 expands to
989 .SAMPLE
990 process("/usr/bin/foo").function("NAME")
991 .ESAMPLE
992
993 .PP
994 when placed in $prefix/share/systemtap/tapset/PATH/usr/bin/
995
996 .PP
997 If PATH is a process component parameter referring to shared libraries
998 then all processes that map it at runtime would be selected for probing.
999 If PATH is a library component parameter referring to shared libraries
1000 then the process specified by the process component would be selected.
1001 Note that the PATH pattern in a library component will always apply to
1002 libraries statically determined to be in use by the process. However,
1003 you may also specify the full path to any library file even if not
1004 statically needed by the process.
1005
1006 .PP
1007 A .plt probe will probe functions in the program linkage table
1008 corresponding to the rest of the probe point. .plt can be specified
1009 as a shorthand for .plt("*"). The symbol name is available as a
1010 $$name context variable; function arguments are not available, since
1011 PLTs are processed without debuginfo. A .plt.return probe places a
1012 probe at the moment \fBafter\fR the return from the named
1013 function.
1014
1015 .PP
1016 If the PATH string contains wildcards as in the MPATTERN case, then
1017 standard globbing is performed to find all matching paths. In this
1018 case, the
1019 .BR $PATH
1020 environment variable is not used.
1021
1022 .PP
1023 If systemtap was invoked with the
1024 .IR \-c " or " \-x
1025 options, then process probes are restricted to the process
1026 hierarchy associated with the target process.
1027
1028 .SS DEBUGINFOD
1029 These probes take the form
1030 .SAMPLE
1031 debuginfod.process("PATH").**
1032 .ESAMPLE
1033 .PP
1034 They are very similar to the process("PATH").** probe family.
1035 The key difference is that the process probes search for
1036 .I PATH
1037 in the host filesystem, while debuginfod probes
1038 search the current federation of debuginfod servers, using the
1039 currently defined
1040 .BR $DEBUGINFOD_URLS
1041 (see
1042 .I debuginfod(8)
1043 ).
1044
1045 .PP
1046 In order to probe the contents of one or more elf/archive files
1047 and/or elf/archive containing directories, the below will create
1048 a debuginfod server which will scan and process the elf files within
1049 and prepare them for systemtap.
1050 .SAMPLE
1051 $ debuginfod [options] [-F -R -Z etc.] /path1 /path2
1052 $ env DEBUGINFOD_URLS=http://localhost:8002/ stap ...
1053 .ESAMPLE
1054
1055 .SS JAVA
1056 Support for probing Java methods is available using Byteman as a
1057 backend. Byteman is an instrumentation tool from the JBoss project
1058 which systemtap can use to monitor invocations for a specific method
1059 or line in a Java program.
1060 .PP
1061 Systemtap does so by generating a Byteman script listing the probes to
1062 instrument and then invoking the Byteman
1063 .IR bminstall
1064 utility.
1065 .PP
1066 This Java instrumentation support is currently a prototype feature
1067 with major limitations. Moreover, Java probing currently does not
1068 work across users; the stap script must run (with appropriate
1069 permissions) under the same user that the Java process being
1070 probed. (Thus a stap script under root currently cannot probe Java
1071 methods in a non-root-user Java process.)
1072
1073 .PP
1074 The first probe type refers to Java processes by the name of the Java process:
1075 .SAMPLE
1076 java("PNAME").class("CLASSNAME").method("PATTERN")
1077 java("PNAME").class("CLASSNAME").method("PATTERN").return
1078 .ESAMPLE
1079 The PNAME argument must be a pre-existing jvm pid, and be identifiable
1080 via a jps listing.
1081 .PP
1082 The PATTERN parameter specifies the signature of the Java method to
1083 probe. The signature must consist of the exact name of the method,
1084 followed by a bracketed list of the types of the arguments, for
1085 instance "myMethod(int,double,Foo)". Wildcards are not supported.
1086 .PP
1087 The probe can be set to trigger at a specific line within the method
1088 by appending a line number with colon, just as in other types of
1089 probes: "myMethod(int,double,Foo):245".
1090 .PP
1091 The CLASSNAME parameter identifies the Java class the method belongs
1092 to, either with or without the package qualification. By default, the
1093 probe only triggers on descendants of the class that do not override
1094 the method definition of the original class. However, CLASSNAME can
1095 take an optional caret prefix, as in
1096 .IR ^org.my.MyClass,
1097 which specifies that the probe should also trigger on all descendants
1098 of MyClass that override the original method. For instance, every method
1099 with signature foo(int) in program org.my.MyApp can be probed at once using
1100 .SAMPLE
1101 java("org.my.MyApp").class("^java.lang.Object").method("foo(int)")
1102 .ESAMPLE
1103 .PP
1104 The second probe type works analogously, but refers to Java processes by PID:
1105 .SAMPLE
1106 java(PID).class("CLASSNAME").method("PATTERN")
1107 java(PID).class("CLASSNAME").method("PATTERN").return
1108 .ESAMPLE
1109 (PIDs for an already running process can be obtained using the
1110 .IR jps (1)
1111 utility.)
1112 .PP
1113 Context variables defined within java probes include
1114 .IR $arg1
1115 through
1116 .IR $arg10
1117 (for up to the first 10 arguments of a method), represented as character-pointers
1118 for the
1119 .B toString()
1120 form of each actual argument.
1121 The
1122 .IR arg1
1123 through
1124 .IR arg10
1125 script variables provide access to these as ordinary strings, fetched via
1126 .IR user_string_warn() .
1127 .PP
1128 Prior to systemtap version 3.1,
1129 .IR $arg1
1130 through
1131 .IR $arg10
1132 could contain either integers or character pointers, depending on the types of the
1133 objects being passed to each particular java method. This previous behaviour may
1134 be invoked with the
1135 .I stap --compatible=3.0
1136 flag.
1137
1138 .SS PROCFS
1139
1140 These probe points allow procfs "files" in
1141 /proc/systemtap/MODNAME to be created, read and written using a
1142 permission that may be modified using the proper umask value. Default permissions are 0400 for read
1143 probes, and 0200 for write probes. If both a read and write probe are being
1144 used on the same file, a default permission of 0600 will be used.
1145 Using procfs.umask(0040).read would
1146 result in a 0404 permission set for the file.
1147 .RI ( MODNAME
1148 is the name of the systemtap module). The
1149 .I proc
1150 filesystem is a pseudo-filesystem which is used as an interface to
1151 kernel data structures. There are several probe point variants supported
1152 by the translator:
1153
1154 .SAMPLE
1155 procfs("PATH").read
1156 procfs("PATH").umask(UMASK).read
1157 procfs("PATH").read.maxsize(MAXSIZE)
1158 procfs("PATH").umask(UMASK).maxsize(MAXSIZE)
1159 procfs("PATH").write
1160 procfs("PATH").umask(UMASK).write
1161 procfs.read
1162 procfs.umask(UMASK).read
1163 procfs.read.maxsize(MAXSIZE)
1164 procfs.umask(UMASK).read.maxsize(MAXSIZE)
1165 procfs.write
1166 procfs.umask(UMASK).write
1167 .ESAMPLE
1168
1169 Note that there are a few differences when procfs probes are used in the stapbpf runtime.
1170 .RI FIFO
1171 special files are used instead of proc filesystem files.
1172 These files are created in
1173 /var/tmp/systemtap-USER/MODNAME.
1174 .RI (USER
1175 is the name of the user).
1176 Additionally, users cannot create both read and write probes on the same file.
1177
1178 .I PATH
1179 is the file name (relative to /proc/systemtap/MODNAME or /var/tmp/systemtap-USER/MODNAME) to be created.
1180 If no
1181 .I PATH
1182 is specified (as in the last two variants above),
1183 .I PATH
1184 defaults to "command". The file name "__stdin" is used internally by systemtap
1185 for input probes and should not be used as a
1186 .I PATH
1187 for procfs probes; see the input probe section below.
1188 .PP
1189 When a user reads /proc/systemtap/MODNAME/PATH (normal runtime) or /var/tmp/systemtap-USER/MODNAME (stapbpf runtime), the corresponding
1190 procfs
1191 .I read
1192 probe is triggered. The string data to be read should be assigned to
1193 a variable named
1194 .IR $value ,
1195 like this:
1196
1197 .SAMPLE
1198 procfs("PATH").read { $value = "100\\n" }
1199 .ESAMPLE
1200 .PP
1201 When a user writes into /proc/systemtap/MODNAME/PATH (normal runtime) or /var/tmp/systemtap-USER/MODNAME (stapbpf runtime), the
1202 corresponding procfs
1203 .I write
1204 probe is triggered. The data the user wrote is available in the
1205 string variable named
1206 .IR $value ,
1207 like this:
1208
1209 .SAMPLE
1210 procfs("PATH").write { printf("user wrote: %s", $value) }
1211 .ESAMPLE
1212 .PP
1213 .I MAXSIZE
1214 is the size of the procfs read buffer. Specifying
1215 .I MAXSIZE
1216 allows larger procfs output. If no
1217 .I MAXSIZE
1218 is specified, the procfs read buffer defaults to
1219 .I STP_PROCFS_BUFSIZE
1220 (which defaults to
1221 .IR MAXSTRINGLEN ,
1222 the maximum length of a string).
1223 If setting the procfs read buffers for more than one file is needed,
1224 it may be easiest to override the
1225 .I STP_PROCFS_BUFSIZE
1226 definition.
1227 Here's an example of using
1228 .IR MAXSIZE :
1229
1230 .SAMPLE
1231 procfs.read.maxsize(1024) {
1232 $value = "long string..."
1233 $value .= "another long string..."
1234 $value .= "another long string..."
1235 $value .= "another long string..."
1236 }
1237 .ESAMPLE
1238
1239 .SS INPUT
1240
1241 These probe points make input from stdin available to the script during runtime.
1242 The translator currently supports two variants of this family:
1243 .SAMPLE
1244 input.char
1245 input.line
1246 .ESAMPLE
1247
1248 .BR input.char
1249 is triggered each time a character is read from stdin. The current
1250 character is available in the string variable named
1251 .IR char .
1252 There is no newline buffering; the next character is read from stdin as soon
1253 as it becomes available.
1254
1255 .BR input.line
1256 causes all characters read from stdin to be buffered until a newline is read,
1257 at which point the probe will be triggered. The current line of characters
1258 (including the newline) is made available in a string variable named
1259 .IR line .
1260 Note that no more than MAXSTRINGLEN characters will be buffered. Any additional
1261 characters will not be included in
1262 .IR line .
1263
1264 .PP
1265 Input probes are aliases for
1266 .BR procfs("__stdin").write .
1267 Systemtap reconfigures stdin if the presence of this procfs probe is detected,
1268 therefore "__stdin" should not be used as a path argument for procfs probes.
1269 Additionally, input probes will not work with the -F and --remote options.
1270
1271 .SS NETFILTER HOOKS
1272
1273 These probe points allow observation of network packets using the
1274 netfilter mechanism. A netfilter probe in systemtap corresponds to a
1275 netfilter hook function in the original netfilter probes API. It is
1276 probably more convenient to use
1277 .IR tapset::netfilter (3stap),
1278 which wraps the primitive netfilter hooks and does the work of
1279 extracting useful information from the context variables.
1280
1281 .PP
1282 There are several probe point variants supported by the translator:
1283
1284 .SAMPLE
1285 netfilter.hook("HOOKNAME").pf("PROTOCOL_F")
1286 netfilter.pf("PROTOCOL_F").hook("HOOKNAME")
1287 netfilter.hook("HOOKNAME").pf("PROTOCOL_F").priority("PRIORITY")
1288 netfilter.pf("PROTOCOL_F").hook("HOOKNAME").priority("PRIORITY")
1289 .ESAMPLE
1290
1291 .PP
1292 .I PROTOCOL_F
1293 is the protocol family to listen for, currently one of
1294 .I NFPROTO_IPV4,
1295 .I NFPROTO_IPV6,
1296 .I NFPROTO_ARP,
1297 or
1298 .I NFPROTO_BRIDGE.
1299
1300 .PP
1301 .I HOOKNAME
1302 is the point, or 'hook', in the protocol stack at which to intercept
1303 the packet. The available hook names for each protocol family are
1304 taken from the kernel header files <linux/netfilter_ipv4.h>,
1305 <linux/netfilter_ipv6.h>, <linux/netfilter_arp.h> and
1306 <linux/netfilter_bridge.h>. For instance, allowable hook names for
1307 .I NFPROTO_IPV4
1308 are
1309 .I NF_INET_PRE_ROUTING,
1310 .I NF_INET_LOCAL_IN,
1311 .I NF_INET_FORWARD,
1312 .I NF_INET_LOCAL_OUT,
1313 and
1314 .I NF_INET_POST_ROUTING.
1315
1316 .PP
1317 .I PRIORITY
1318 is an integer priority giving the order in which the probe point
1319 should be triggered relative to any other netfilter hook functions
1320 which trigger on the same packet. Hook functions execute on each
1321 packet in order from smallest priority number to largest priority number. If no
1322 .I PRIORITY
1323 is specified (as in the first two probe point variants above),
1324 .I PRIORITY
1325 defaults to "0".
1326
1327 There are a number of predefined priority names of the form
1328 .I NF_IP_PRI_*
1329 and
1330 .I NF_IP6_PRI_*
1331 which are defined in the kernel header files <linux/netfilter_ipv4.h> and <linux/netfilter_ipv6.h> respectively. The script is permitted to use these
1332 instead of specifying an integer priority. (The probe points for
1333 .I NFPROTO_ARP
1334 and
1335 .I NFPROTO_BRIDGE
1336 currently do not expose any named hook priorities to the script writer.)
1337 Thus, allowable ways to specify the priority include:
1338
1339 .SAMPLE
1340 priority("255")
1341 priority("NF_IP_PRI_SELINUX_LAST")
1342 .ESAMPLE
1343
1344 A script using guru mode is permitted to specify any identifier or
1345 number as the parameter for hook, pf, and priority. This feature
1346 should be used with caution, as the parameter is inserted verbatim into
1347 the C code generated by systemtap.
1348
1349 The netfilter probe points define the following context variables:
1350 .TP
1351 .IR $hooknum
1352 The hook number.
1353 .TP
1354 .IR $skb
1355 The address of the sk_buff struct representing the packet. See
1356 <linux/skbuff.h> for details on how to use this struct, or
1357 alternatively use the tapset
1358 .IR tapset::netfilter (3stap)
1359 for easy access to key information.
1360
1361 .TP
1362 .IR $in
1363 The address of the net_device struct representing the network device
1364 on which the packet was received (if any). May be 0 if the device is
1365 unknown or undefined at that stage in the protocol stack.
1366
1367 .TP
1368 .IR $out
1369 The address of the net_device struct representing the network device
1370 on which the packet will be sent (if any). May be 0 if the device is
1371 unknown or undefined at that stage in the protocol stack.
1372
1373 .TP
1374 .IR $verdict
1375 (Guru mode only.) Assigning one of the verdict values defined in
1376 <linux/netfilter.h> to this variable alters the further progress of
1377 the packet through the protocol stack. For instance, the following
1378 guru mode script forces all ipv6 network packets to be dropped:
1379
1380 .SAMPLE
1381 probe netfilter.pf("NFPROTO_IPV6").hook("NF_IP6_PRE_ROUTING") {
1382 $verdict = 0 /* nf_drop */
1383 }
1384 .ESAMPLE
1385
1386 For convenience, unlike the primitive probe points discussed here, the
1387 probes defined in
1388 .IR tapset::netfilter (3stap)
1389 export the lowercase names of the verdict constants (e.g. NF_DROP
1390 becomes nf_drop) as local variables.
1391
1392 .SS KERNEL TRACEPOINTS
1393
1394 This family of probe points hooks up to static probing tracepoints
1395 inserted into the kernel or modules. As with markers, these
1396 tracepoints are special macro calls inserted by kernel developers to
1397 make probing faster and more reliable than with DWARF-based probes,
1398 and DWARF debugging information is not required to probe tracepoints.
1399 Tracepoints have an extra advantage of more strongly-typed parameters
1400 than markers.
1401
1402 Tracepoint probes look like:
1403 .BR kernel.trace("name") .
1404 The tracepoint name string, which may contain the usual wildcard
1405 characters, is matched against the names defined by the kernel
1406 developers in the tracepoint header files. To restrict the search to
1407 specific subsystems (e.g. sched, ext3, etc...), the following syntax
1408 can be used:
1409 .BR kernel.trace("system:name") .
1410 The tracepoint system string may also contain the usual wildcard
1411 characters.
1412
1413 The handler associated with a tracepoint-based probe may read the
1414 optional parameters specified at the macro call site. These are
1415 named according to the declaration by the tracepoint author. For
1416 example, the tracepoint probe
1417 .BR kernel.trace("sched:sched_switch")
1418 provides the parameters
1419 .BR $prev " and " $next .
1420 If the parameter is a complex type, as in a struct pointer, then a
1421 script can access fields with the same syntax as DWARF $target
1422 variables. Also, tracepoint parameters cannot be modified, but in
1423 guru-mode a script may modify fields of parameters.
1424
1425 The subsystem and name of the tracepoint are available in
1426 .BR $$system " and " $$name
1427 and a string of name=value pairs for all parameters of the tracepoint
1428 is available in
1429 .BR $$vars " or " $$parms .
1430
1431 .SS KERNEL MARKERS (OBSOLETE)
1432
1433 This family of probe points hooks up to an older style of static
1434 probing markers inserted into older kernels or modules. These markers
1435 are special STAP_MARK macro calls inserted by kernel developers to
1436 make probing faster and more reliable than with DWARF-based probes.
1437 Further, DWARF debugging information is
1438 .I not
1439 required to probe markers.
1440
1441 Marker probe points begin with
1442 .BR kernel .
1443 The next part names the marker itself:
1444 .BR mark("name") .
1445 The marker name string, which may contain the usual wildcard characters,
1446 is matched against the names given to the marker macros when the kernel
1447 and/or module was compiled. Optionally, you can specify
1448 .BR format("format") .
1449 Specifying the marker format string allows differentiation between two
1450 markers with the same name but different marker format strings.
1451
1452 The handler associated with a marker-based probe may read the
1453 optional parameters specified at the macro call site. These are
1454 named
1455 .BR $arg1 " through " $argNN ,
1456 where NN is the number of parameters supplied by the macro. Number
1457 and string parameters are passed in a type-safe manner.
1458
1459 The marker format string associated with a marker is available in
1460 .BR $format .
1461 And also the marker name string is available in
1462 .BR $name .
1463
1464 .SS KERNEL HARDWARE BREAKPOINTS
1465 This family of probes is used to set hardware watchpoints for a given
1466 (global) kernel symbol. The probes take three components as inputs :
1467
1468 1. The
1469 .BR virtual
1470 address / name of the kernel symbol to be traced is supplied as
1471 argument to this class of probes. ( Probes for only data segment
1472 variables are supported. Probing local variables of a function cannot
1473 be done.)
1474
1475 2. Nature of access to be probed :
1476 a.
1477 .I .write
1478 probe gets triggered when a write happens at the specified address/symbol
1479 name.
1480 b.
1481 .I rw
1482 probe is triggered when either a read or write happens.
1483
1484 3.
1485 .BR .length
1486 (optional)
1487 Users have the option of specifying the address interval to be probed
1488 using "length" constructs. The user-specified length gets approximated
1489 to the closest possible address length that the architecture can
1490 support. If the specified length exceeds the limits imposed by
1491 architecture, an error message is flagged and probe registration fails.
1492 Wherever 'length' is not specified, the translator requests a hardware
1493 breakpoint probe of length 1. It should be noted that the "length"
1494 construct is not valid with symbol names.
1495
1496 Following constructs are supported :
1497 .SAMPLE
1498 probe kernel.data(ADDRESS).write
1499 probe kernel.data(ADDRESS).rw
1500 probe kernel.data(ADDRESS).length(LEN).write
1501 probe kernel.data(ADDRESS).length(LEN).rw
1502 probe kernel.data("SYMBOL_NAME").write
1503 probe kernel.data("SYMBOL_NAME").rw
1504 .ESAMPLE
1505
1506 This set of probes make use of the debug registers of the processor,
1507 which is a scarce resource. (4 on x86 , 1 on powerpc ) The script
1508 translation flags a warning if a user requests more hardware breakpoint probes
1509 than the limits set by architecture. For example,a pass-2 warning is flashed
1510 when an input script requests 5 hardware breakpoint probes on an x86
1511 system while x86 architecture supports a maximum of 4 breakpoints.
1512 Users are cautioned to set probes judiciously.
1513
1514 It is possible to specify userspace virtual memory addresses in this
1515 family of probes and the handlers would trigger upon the corresponding
1516 memory read/write events in those processes. But one cannot easily control
1517 which processes are monitored. Using `if (pid() == target())` is a workaround
1518 but it is inefficient. Better use the userland hardware breakpoint probes
1519 below instead.
1520
1521 .SS USERLAND HARDWARE BREAKPOINTS
1522
1523 This family of probes is very similar to its kernel-space counterpart
1524 but it targets the userland processes only.
1525
1526 The following constructs are currently supported:
1527 .SAMPLE
1528 probe process.data(ADDRESS).write
1529 probe process.data(ADDRESS).rw
1530 probe process.data(ADDRESS).length(LEN).write
1531 probe process.data(ADDRESS).length(LEN).rw
1532 .ESAMPLE
1533
1534 Currently, only the target process specified by -x PID or -c CMD has
1535 the watchpoints registered. The ADDRESS must be a valid virtual memory
1536 address in that process's address space.
1537
1538 .SS PERF
1539
1540 This family of probe points interfaces to the kernel "perf event"
1541 infrastructure for controlling hardware performance counters.
1542 The events being attached to are described by the "type",
1543 "config" fields of the
1544 .IR perf_event_attr
1545 structure, and are sampled at an interval governed by the
1546 "sample_period" and "sample_freq" fields.
1547
1548 These fields are made available to systemtap scripts using
1549 the following syntax:
1550 .SAMPLE
1551 probe perf.type(NN).config(MM).sample(XX)
1552 probe perf.type(NN).config(MM).hz(XX)
1553 probe perf.type(NN).config(MM)
1554 probe perf.type(NN).config(MM).process("PROC")
1555 probe perf.type(NN).config(MM).counter("COUNTER")
1556 probe perf.type(NN).config(MM).process("PROC").counter("NAME")
1557 .ESAMPLE
1558 The systemtap probe handler is called once per XX increments
1559 of the underlying performance counter when using the .sample field
1560 or at a frequency in hertz when using the .hz field. When not specified,
1561 the default behavior is to sample at a count of 1000000.
1562 The range of valid type/config is described by the
1563 .IR perf_event_open (2)
1564 system call, and/or the
1565 .IR linux/perf_event.h
1566 file. Invalid combinations or exhausted hardware counter resources
1567 result in errors during systemtap script startup. Systemtap does
1568 not sanity-check the values: it merely passes them through to
1569 the kernel for error- and safety-checking. By default the perf event
1570 probe is systemwide unless .process is specified, which will bind the
1571 probe to a specific task. If the name is omitted then it
1572 is inferred from the stap \-c argument. A perf event can be read on
1573 demand using .counter. The body of the perf probe handler will not be
1574 invoked for a .counter probe; instead, the counter is read in a user
1575 space probe via:
1576 .TP
1577 process("PROC").statement("func@file") {stat <<< @perf("NAME")}
1578
1579
1580 .SS PYTHON
1581 Support for probing python 2 and python 3 function is available with
1582 the help of an extra python support module. Note that the debuginfo
1583 for the version of python being probed is required. To run a python
1584 script with the extra python support module you'd add the '-m
1585 HelperSDT' option to your python command, like this:
1586 .SAMPLE
1587 stap foo.stp -c "python -m HelperSDT foo.py"
1588 .ESAMPLE
1589 Python probes look like the following:
1590 .SAMPLE
1591 python2.module("MPATTERN").function("PATTERN")
1592 python2.module("MPATTERN").function("PATTERN").call
1593 python2.module("MPATTERN").function("PATTERN").return
1594 python3.module("MPATTERN").function("PATTERN")
1595 python3.module("MPATTERN").function("PATTERN").call
1596 python3.module("MPATTERN").function("PATTERN").return
1597 .ESAMPLE
1598 The list above includes multiple variants and modifiers which provide
1599 additional functionality or filters. They are:
1600 .RS
1601 .TP
1602 \fB.function\fR
1603 Places a probe at the beginning of the named function by
1604 default, unless modified by PATTERN. Parameters are available as
1605 context variables.
1606 .TP
1607 \fB.call\fR
1608 Places a probe at the beginning of the named function. Parameters are
1609 available as context variables.
1610 .TP
1611 \fB.return\fR
1612 Places a probe at the moment \fBbefore\fR the return from the named
1613 function. Parameters and local/global python variables are available
1614 as context variables.
1615 .RE
1616 .PP
1617 PATTERN stands for a string literal that aims to identify a point in
1618 the python program. It is made up of three parts:
1619 .IP \(bu 4
1620 The first part is the name of a function (e.g. "foo") or class method
1621 (e.g. "bar.baz"). This part may use the "*" and "?" wildcarding
1622 operators to match multiple names.
1623 .IP \(bu 4
1624 The second part is optional and begins with the "@" character.
1625 It is followed by the path to the source file containing the function,
1626 which may include a wildcard pattern. The python path is searched for
1627 a matching filename.
1628 .IP \(bu 4
1629 Finally, the third part is optional if the file name part was given,
1630 and identifies the line number in the source file preceded by a ":"
1631 or a "+". The line number is assumed to be an
1632 absolute line number if preceded by a ":", or relative to the
1633 declaration line of the function if preceded by a "+".
1634 All the lines in the function can be matched with ":*".
1635 A range of lines x through y can be matched with ":x\-y". Ranges and
1636 specific lines can be mixed using commas, e.g. ":x,y\-z".
1637 .PP
1638 In the above list of probe points, MPATTERN stands for a python module
1639 or script name that names the python module of interest. This part may
1640 use the "*" and "?" wildcarding operators to match multiple names. The
1641 python path is searched for a matching filename.
1642
1643
1644 .SH EXAMPLES
1645 .PP
1646 Here are some example probe points, defining the associated events.
1647 .TP
1648 begin, end, end
1649 refers to the startup and normal shutdown of the session. In this
1650 case, the handler would run once during startup and twice during
1651 shutdown.
1652 .TP
1653 timer.jiffies(1000).randomize(200)
1654 refers to a periodic interrupt, every 1000 +/\- 200 jiffies.
1655 .TP
1656 kernel.function("*init*"), kernel.function("*exit*")
1657 refers to all kernel functions with "init" or "exit" in the name.
1658 .TP
1659 kernel.function("*@kernel/time.c:240")
1660 refers to any functions within the "kernel/time.c" file that span
1661 line 240.
1662 .BR
1663 Note
1664 that this is
1665 .BR not
1666 a probe at the statement at that line number. Use the
1667 .IR
1668 kernel.statement
1669 probe instead.
1670 .TP
1671 kernel.trace("sched_*")
1672 refers to all scheduler-related (really, prefixed) tracepoints in
1673 the kernel.
1674 .TP
1675 kernel.mark("getuid")
1676 refers to an obsolete STAP_MARK(getuid, ...) macro call in the kernel.
1677 .TP
1678 module("usb*").function("*sync*").return
1679 refers to the moment of return from all functions with "sync" in the
1680 name in any of the USB drivers.
1681 .TP
1682 kernel.statement(0xc0044852)
1683 refers to the first byte of the statement whose compiled instructions
1684 include the given address in the kernel.
1685 .TP
1686 kernel.statement("*@kernel/time.c:296")
1687 refers to the statement of line 296 within "kernel/time.c".
1688 .TP
1689 kernel.statement("bio_init@fs/bio.c+3")
1690 refers to the statement at line bio_init+3 within "fs/bio.c".
1691 .TP
1692 kernel.data("pid_max").write
1693 refers to a hardware breakpoint of type "write" set on pid_max
1694 .TP
1695 syscall.*.return
1696 refers to the group of probe aliases with any name in the third position
1697
1698 .SH SEE ALSO
1699 .nh
1700 .nf
1701 .IR stap (1),
1702 .IR probe::* (3stap),
1703 .IR tapset::* (3stap)
1704
1705 .\" Local Variables:
1706 .\" mode: nroff
1707 .\" End: