1STAPPROBES(3stap) STAPPROBES(3stap)
2
6 stapprobes - systemtap probe points
7
11 The following sections enumerate the variety of probe points supported
12 by the systemtap translator, and some of the additional aliases defined
13 by standard tapset scripts. Many are individually documented in the
14 3stap manual section, with the probe:: prefix.
15
18 probe PROBEPOINT [, PROBEPOINT] { [STMT ...] }
19 A probe declaration may list multiple comma-separated probe points in
22 order to attach a handler to all of the named events. Normally, the
23 handler statements are run whenever any of events occur. Depending on
24 the type of probe point, the handler statements may refer to context
25 variables (denoted with a dollar-sign prefix like $foo) to read or
26 write state. This may include function parameters for function probes,
27 or local variables for statement probes.
28 The syntax of a single probe point is a general dotted-symbol sequence.
30 This allows a breakdown of the event namespace into parts, somewhat
31 like the Domain Name System does on the Internet. Each component iden‐
32 tifier may be parametrized by a string or number literal, with a syntax
33 like a function call. A component may include a "*" character, to ex‐
34 pand to a set of matching probe points. It may also include "**" to
35 match multiple sequential components at once. Probe aliases likewise
36 expand to other probe points.
37 Probe aliases can be given on their own, or with a suffix. The suffix
39 attaches to the underlying probe point that the alias is expanded to.
40 For example,
41 syscall.read.return.maxactive(10)
43 expands to
45 kernel.function("sys_read").return.maxactive(10)
47 with the component maxactive(10) being recognized as a suffix.
49 Normally, each and every probe point resulting from wildcard- and
51 alias-expansion must be resolved to some low-level system instrumenta‐
52 tion facility (e.g., a kprobe address, marker, or a timer configura‐
53 tion), otherwise the elaboration phase will fail.
54 However, a probe point may be followed by a "?" character, to indicate
56 that it is optional, and that no error should result if it fails to re‐
57 solve. Optionalness passes down through all levels of alias/wildcard
58 expansion. Alternately, a probe point may be followed by a "!" charac‐
59 ter, to indicate that it is both optional and sufficient. (Think
60 vaguely of the Prolog cut operator.) If it does resolve, then no fur‐
61 ther probe points in the same comma-separated list will be resolved.
62 Therefore, the "!" sufficiency mark only makes sense in a list of
63 probe point alternatives.
64 Additionally, a probe point may be followed by a "if (expr)" statement,
66 in order to enable/disable the probe point on-the-fly. With the "if"
67 statement, if the "expr" is false when the probe point is hit, the
68 whole probe body including alias's body is skipped. The condition is
69 stacked up through all levels of alias/wildcard expansion. So the final
70 condition becomes the logical-and of conditions of all expanded
71 alias/wildcard. The expressions are necessarily restricted to global
72 variables.
73 These are all syntactically valid probe points. (They are generally
75 semantically invalid, depending on the contents of the tapsets, and the
76 versions of kernel/user software installed.)
77 kernel.function("foo").return
80 process("/bin/vi").statement(0x2222)
81 end
82 syscall.*
83 syscall.*.return.maxactive(10)
84 syscall.{open,close}
85 sys**open
86 kernel.function("no_such_function") ?
87 module("awol").function("no_such_function") !
88 signal.*? if (switch)
89 kprobe.function("foo")
90 Probes may be broadly classified into "synchronous" and "asynchronous".
93 A "synchronous" event is deemed to occur when any processor executes an
94 instruction matched by the specification. This gives these probes a
95 reference point (instruction address) from which more contextual data
96 may be available. Other families of probe points refer to "asynchro‐
97 nous" events such as timers/counters rolling over, where there is no
98 fixed reference point that is related. Each probe point specification
99 may match multiple locations (for example, using wildcards or aliases),
100 and all them are then probed. A probe declaration may also contain
101 several comma-separated specifications, all of which are probed.
102 Brace expansion is a mechanism which allows a list of probe points to
104 be generated. It is very similar to shell expansion. A component may be
105 surrounded by a pair of curly braces to indicate that the comma-sepa‐
106 rated sequence of one or more subcomponents will each constitute a new
107 probe point. The braces may be arbitrarily nested. The ordering of ex‐
108 panded results is based on product order.
109 The question mark (?), exclamation mark (!) indicators and probe point
111 conditions may not be placed in any expansions that are before the last
112 component.
113 The following is an example of brace expansion.
115 syscall.{write,read}
118 # Expands to
119 syscall.write, syscall.read
120 {kernel,module("nfs")}.function("nfs*")!
122 # Expands to
123 kernel.function("nfs*")!, module("nfs").function("nfs*")!
124
128 Resolving some probe points requires DWARF debuginfo or "debug symbols"
129 for the specific program being instrumented. For some others, DWARF is
130 automatically synthesized on the fly from source code header files.
131 For others, it is not needed at all. Since a systemtap script may use
132 any mixture of probe points together, the union of their DWARF require‐
133 ments has to be met on the computer where script compilation occurs.
134 (See the --use-server option and the stap-server(8) man page for infor‐
135 mation about the remote compilation facility, which allows these re‐
136 quirements to be met on a different machine.)
137 The following point lists many of the available probe point families,
139 to classify them with respect to their need for DWARF debuginfo for the
140 specific program for that probe point.
141 DWARF NON-DWARF SYMBOL-TABLE
144 kernel.function, .statement kernel.mark kernel.function*
146 module.function, .statement process.mark, process.plt module.function*
147 process.function, .statement begin, end, error, never process.function*
148 process.mark* timer
149 .function.callee perf
150 python2, python3 procfs
151 kernel.statement.absolute
152 AUTO-GENERATED-DWARF kernel.data
153 kprobe.function
154 kernel.trace process.statement.absolute
155 process.begin, .end
156 netfilter
157 java
158 The probe types marked with * asterisks mark fallbacks, where systemtap
161 can sometimes infer subset or substitute information. In general, the
162 more symbolic / debugging information available, the higher quality
163 probing will be available.
164
168 The following types of probe points may be armed/disarmed on-the-fly to
169 save overheads during uninteresting times. Arming conditions may also
170 be added to other types of probes, but will be treated as a wrapping
171 conditional and won't benefit from overhead savings.
172 DISARMABLE exceptions
175 kernel.function, kernel.statement
176 module.function, module.statement
177 process.*.function, process.*.statement
178 process.*.plt, process.*.mark
179 timer. timer.profile
180 java
181
184 BEGIN/END/ERROR
185 The probe points begin and end are defined by the translator to refer
186 to the time of session startup and shutdown. All "begin" probe han‐
187 dlers are run, in some sequence, during the startup of the session.
188 All global variables will have been initialized prior to this point.
189 All "end" probes are run, in some sequence, during the normal shutdown
190 of a session, such as in the aftermath of an exit () function call, or
191 an interruption from the user. In the case of an error-triggered shut‐
192 down, "end" probes are not run. There are no target variables avail‐
193 able in either context.
194 If the order of execution among "begin" or "end" probes is significant,
196 then an optional sequence number may be provided:
197 begin(N)
200 end(N)
201 The number N may be positive or negative. The probe handlers are run
204 in increasing order, and the order between handlers with the same se‐
205 quence number is unspecified. When "begin" or "end" are given without
206 a sequence, they are effectively sequence zero.
207 The error probe point is similar to the end probe, except that each
209 such probe handler run when the session ends after errors have oc‐
210 curred. In such cases, "end" probes are skipped, but each "error"
211 probe is still attempted. This kind of probe can be used to clean up
212 or emit a "final gasp". It may also be numerically parametrized to set
213 a sequence.
214 NEVER
217 The probe point never is specially defined by the translator to mean
218 "never". Its probe handler is never run, though its statements are an‐
219 alyzed for symbol / type correctness as usual. This probe point may be
220 useful in conjunction with optional probes.
221 SYSCALL and ND_SYSCALL
224 The syscall.* and nd_syscall.* aliases define several hundred probes,
225 too many to detail here. They are of the general form:
226 syscall.NAME
229 nd_syscall.NAME
230 syscall.NAME.return
231 nd_syscall.NAME.return
232 Generally, a pair of probes are defined for each normal system call as
235 listed in the syscalls(2) manual page, one for entry and one for re‐
236 turn. Those system calls that never return do not have a corresponding
237 .return probe. The nd_* family of probes are about the same, except it
238 uses non-DWARF based searching mechanisms, which may result in a lower
239 quality of symbolic context data (parameters), and may miss some system
240 calls. You may want to try them first, in case kernel debugging infor‐
241 mation is not immediately available.
242 Each probe alias provides a variety of variables. Looking at the tapset
244 source code is the most reliable way. Generally, each variable listed
245 in the standard manual page is made available as a script-level vari‐
246 able, so syscall.open exposes filename, flags, and mode. In addition,
247 a standard suite of variables is available at most aliases:
248 argstr A pretty-printed form of the entire argument list, without
250 parentheses.
251 name The name of the system call.
253 retval For return probes, the raw numeric system-call result.
255 retstr For return probes, a pretty-printed string form of the system-
257 call result.
258 As usual for probe aliases, these variables are all initialized once
260 from the underlying $context variables, so that later changes to $con‐
261 text variables are not automatically reflected. Not all probe aliases
262 obey all of these general guidelines. Please report any bothersome
263 ones you encounter as a bug. Note that on some kernel/userspace archi‐
264 tecture combinations (e.g., 32-bit userspace on 64-bit kernel), the un‐
265 derlying $context variables may need explicit sign extension / masking.
266 When this is an issue, consider using the tapset-provided variables in‐
267 stead of raw $context variables.
268 If debuginfo availability is a problem, you may try using the non-DWARF
270 syscall probe aliases instead. Use the nd_syscall. prefix instead of
271 syscall. The same context variables are available, as far as possible.
272 nd_syscall probes on kernels that use syscall wrappers to pass argu‐
274 ments via pt_regs (currently 4.17+ on x86_64 and 4.19+ on aarch64) sup‐
275 port syscall argument writing when guru mode is enabled. If a probe
276 syscall parameter is modified in the probe body then immediately before
277 the probe exits the parameter's current value will be written to
278 pt_regs. This overwrites the previous value. nd_syscall probes also
279 include two parameters for each of the syscall's string parameters.
280 One holds a quoted version of the string passed to the syscall. The
281 other holds an unquoted version of the string intended to be used when
282 modifying the parameter. If the probe modifies the unquoted string
283 variable then as the probe is about to exit the contents of this vari‐
284 able will be written to the user space buffer passed to the syscall. It
285 is the user's responsibility to ensure that this buffer is large enough
286 to hold the modified string and that it is located in a writable memory
287 segment.
288 TIMERS
291 There are two main types of timer probes: "jiffies" timer probes and
292 time interval timer probes.
293 Intervals defined by the standard kernel "jiffies" timer may be used to
295 trigger probe handlers asynchronously. Two probe point variants are
296 supported by the translator:
297 timer.jiffies(N)
300 timer.jiffies(N).randomize(M)
301 The probe handler is run every N jiffies (a kernel-defined unit of
304 time, typically between 1 and 60 ms). If the "randomize" component is
305 given, a linearly distributed random value in the range [-M..+M] is
306 added to N every time the handler is run. N is restricted to a reason‐
307 able range (1 to around a million), and M is restricted to be smaller
308 than N. There are no target variables provided in either context. It
309 is possible for such probes to be run concurrently on a multi-processor
310 computer.
311 Alternatively, intervals may be specified in units of time. There are
313 two probe point variants similar to the jiffies timer:
314 timer.ms(N)
317 timer.ms(N).randomize(M)
318 Here, N and M are specified in milliseconds, but the full options for
321 units are seconds (s/sec), milliseconds (ms/msec), microseconds
322 (us/usec), nanoseconds (ns/nsec), and hertz (hz). Randomization is not
323 supported for hertz timers.
324 The actual resolution of the timers depends on the target kernel. For
326 kernels prior to 2.6.17, timers are limited to jiffies resolution, so
327 intervals are rounded up to the nearest jiffies interval. After
328 2.6.17, the implementation uses hrtimers for tighter precision, though
329 the actual resolution will be arch-dependent. In either case, if the
330 "randomize" component is given, then the random value will be added to
331 the interval before any rounding occurs.
332 Profiling timers are also available to provide probes that execute on
334 all CPUs at the rate of the system tick (CONFIG_HZ) or at a given fre‐
335 quency (hz). On some kernels, this is a one-concurrent-user-only or
336 disabled facility, resulting in error -16 (EBUSY) during probe regis‐
337 tration.
338 timer.profile.tick
341 timer.profile.freq.hz(N)
342 Full context information of the interrupted process is available, mak‐
345 ing this probe suitable for a time-based sampling profiler.
346 It is recommended to use the tapset probe timer.profile rather than
348 timer.profile.tick. This probe point behaves identically to timer.pro‐
349 file.tick when the underlying functionality is available, and falls
350 back to using perf.sw.cpu_clock on some recent kernels which lack the
351 corresponding profile timer facility.
352 Profiling timers with specified frequencies are only accurate up to
354 around 100 hz. You may need to provide a larger value to achieve the
355 desired rate.
356 Note that if a timer probe is set to fire at a very high rate and if
358 the probe body is complex, succeeding timer probes can get skipped,
359 since the time for them to run has already passed. Normally systemtap
360 reports missed probes, but it will not report these skipped probes.
361 DWARF
364 This family of probe points uses symbolic debugging information for the
365 target kernel/module/program, as may be found in unstripped executa‐
366 bles, or the separate debuginfo packages. They allow placement of
367 probes logically into the execution path of the target program, by
368 specifying a set of points in the source or object code. When a match‐
369 ing statement executes on any processor, the probe handler is run in
370 that context.
371 Probe points in the DWARF family can be identified by the target kernel
373 module (or user process), source file, line number, function name, or
374 some combination of these.
375 Here is a list of DWARF probe points currently supported:
377 kernel.function(PATTERN)
379 kernel.function(PATTERN).call
380 kernel.function(PATTERN).callee(PATTERN)
381 kernel.function(PATTERN).callee(PATTERN).return
382 kernel.function(PATTERN).callee(PATTERN).call
383 kernel.function(PATTERN).callees(DEPTH)
384 kernel.function(PATTERN).return
385 kernel.function(PATTERN).inline
386 kernel.function(PATTERN).label(LPATTERN)
387 module(MPATTERN).function(PATTERN)
388 module(MPATTERN).function(PATTERN).call
389 module(MPATTERN).function(PATTERN).callee(PATTERN)
390 module(MPATTERN).function(PATTERN).callee(PATTERN).return
391 module(MPATTERN).function(PATTERN).callee(PATTERN).call
392 module(MPATTERN).function(PATTERN).callees(DEPTH)
393 module(MPATTERN).function(PATTERN).return
394 module(MPATTERN).function(PATTERN).inline
395 module(MPATTERN).function(PATTERN).label(LPATTERN)
396 kernel.statement(PATTERN)
397 kernel.statement(PATTERN).nearest
398 kernel.statement(ADDRESS).absolute
399 module(MPATTERN).statement(PATTERN)
400 process("PATH").function("NAME")
401 process("PATH").statement("*@FILE.c:123")
402 process("PATH").library("PATH").function("NAME")
403 process("PATH").library("PATH").statement("*@FILE.c:123")
404 process("PATH").library("PATH").statement("*@FILE.c:123").nearest
405 process("PATH").function("*").return
406 process("PATH").function("myfun").label("foo")
407 process("PATH").function("foo").callee("bar")
408 process("PATH").function("foo").callee("bar").return
409 process("PATH").function("foo").callee("bar").call
410 process("PATH").function("foo").callees(DEPTH)
411 process(PID).function("NAME")
412 process(PID).function("myfun").label("foo")
413 process(PID).plt("NAME")
414 process(PID).plt("NAME").return
415 process(PID).statement("*@FILE.c:123")
416 process(PID).statement("*@FILE.c:123").nearest
417 process(PID).statement(ADDRESS).absolute
418 (See the USER-SPACE section below for more information on the process
420 probes.)
421 The list above includes multiple variants and modifiers which provide
423 additional functionality or filters. They are:
424 .function
426 Places a probe near the beginning of the named function,
427 so that parameters are available as context variables.
428 .return
430 Places a probe at the moment after the return from the
431 named function, so the return value is available as the
432 "$return" context variable.
433 .inline
435 Filters the results to include only instances of inlined
436 functions. Note that inlined functions do not have an
437 identifiable return point, so .return is not supported on
438 .inline probes.
439 .call Filters the results to include only non-inlined functions
441 (the opposite set of .inline)
442 .exported
444 Filters the results to include only exported functions.
445 .statement
447 Places a probe at the exact spot, exposing those local
448 variables that are visible there.
449 .statement.nearest
451 Places a probe at the nearest available line number for
452 each line number given in the statement.
453 .callee
455 Places a probe on the callee function given in the
456 .callee modifier, where the callee must be a function
457 called by the target function given in .function. The ad‐
458 vantage of doing this over directly probing the callee
459 function is that this probe point is run only when the
460 callee is called from the target function (add the
461 -DSTAP_CALLEE_MATCHALL directive to override this when
462 calling stap(1)).
463 Note that only callees that can be statically determined
465 are available. For example, calls through function
466 pointers are not available. Additionally, calls to func‐
467 tions located in other objects (e.g. libraries) are not
468 available (instead use another probe point). This feature
469 will only work for code compiled with GCC 4.7+.
470 .callees
472 Shortcut for .callee("*"), which places a probe on all
473 callees of the function.
474 .callees(DEPTH)
476 Recursively places probes on callees. For example,
477 .callees(2) will probe both callees of the target func‐
478 tion, as well as callees of those callees. And
479 .callees(3) goes one level deeper, etc... A callee probe
480 at depth N is only triggered when the N callers in the
481 callstack match those that were statically determined
482 during analysis (this also may be overridden using
483 -DSTAP_CALLEE_MATCHALL).
484 In the above list of probe points, MPATTERN stands for a string literal
486 that aims to identify the loaded kernel module of interest. For in-tree
487 kernel modules, the name suffices (e.g. "btrfs"). The name may also in‐
488 clude the "*", "[]", and "?" wildcards to match multiple in-tree mod‐
489 ules. Out-of-tree modules are also supported by specifying the full
490 path to the ko file. Wildcards are not supported. The file must follow
491 the convention of being named <module_name>.ko (characters ',' and '-'
492 are replaced by '_').
493 LPATTERN stands for a source program label. It may also contain "*",
495 "[]", and "?" wildcards. PATTERN stands for a string literal that aims
496 to identify a point in the program. It is made up of three parts:
497 · The first part is the name of a function, as would appear in the nm
499 program's output. This part may use the "*" and "?" wildcarding
500 operators to match multiple names.
501 · The second part is optional and begins with the "@" character. It
503 is followed by the path to the source file containing the function,
504 which may include a wildcard pattern, such as mm/slab*. If it does
505 not match as is, an implicit "*/" is optionally added before the
506 pattern, so that a script need only name the last few components of
507 a possibly long source directory path.
508 · Finally, the third part is optional if the file name part was giv‐
510 en, and identifies the line number in the source file preceded by a
511 ":" or a "+". The line number is assumed to be an absolute line
512 number if preceded by a ":", or relative to the declaration line of
513 the function if preceded by a "+". All the lines in the function
514 can be matched with ":*". A range of lines x through y can be
515 matched with ":x-y". Ranges and specific lines can be mixed using
516 commas, e.g. ":x,y-z".
517 As an alternative, PATTERN may be a numeric constant, indicating an ad‐
519 dress. Such an address may be found from symbol tables of the appro‐
520 priate kernel / module object file. It is verified against known
521 statement code boundaries, and will be relocated for use at run time.
522 In guru mode only, absolute kernel-space addresses may be specified
524 with the ".absolute" suffix. Such an address is considered already re‐
525 located, as if it came from /proc/kallsyms, so it cannot be checked
526 against statement/instruction boundaries.
527 CONTEXT VARIABLES
530 Many of the source-level context variables, such as function parame‐
531 ters, locals, globals visible in the compilation unit, may be visible
532 to probe handlers. They may refer to these variables by prefixing
533 their name with "$" within the scripts. In addition, a special syntax
534 allows limited traversal of structures, pointers, and arrays. More
535 syntax allows pretty-printing of individual variables or their groups.
536 See also @cast. Note that variables may be inaccessible due to them
537 being paged out, or for a few other reasons. See also man er‐
538 ror::fault(7stap).
539 Functions called from DWARF class probe points and from process.mark
542 probes may also refer to context variables.
543 $var refers to an in-scope variable or thread local storage variable
546 "var". If it's an integer-like type, it will be cast to a
547 64-bit int for systemtap script use. String-like pointers (char
548 *) may be copied to systemtap string values using the ker‐
549 nel_string or user_string functions.
550 @var("varname")
552 an alternative syntax for $varname
553 @var("varname","module")
555 The global variable or global thread local storage variable in
556 scope of the given module already loaded into the current probed
557 process. Useful to get an exported variable in a shared library
558 loaded into the process being probed, or a global variable in a
559 process while a shared library probe is being executed. For us‐
560 er-space modules only. For example: @var("_r_debug","/lib/ld-
561 linux.so.2")
562 @var("varname@src/file.c")
564 refers to the global (either file local or external) variable
565 varname defined when the file src/file.c was compiled. The CU in
566 which the variable is resolved is the first CU in the module of
567 the probe point which matches the given file name at the end and
568 has the shortest file name path (e.g. given
569 @var("foo@bar/baz.c") and CUs with file name paths src/sub/mod‐
570 ule/bar/baz.c and src/bar/baz.c the second CU will be chosen to
571 resolve the (file) global variable foo
572 @var("varname@src/file.c","module")
575 The global variable in scope of the given CU, defined in the
576 given module, even if the variable is static (so the name is not
577 unique without the CU name).
578 $var->field traversal via a structure's or a pointer's field. This
581 generalized indirection operator may be repeated to follow more
582 levels. Note that the . operator is not used for plain struc‐
583 ture members, only -> for both purposes. (This is because "."
584 is reserved for string concatenation.) Also note that for direct
585 dereferencing of $var pointer {kernel,user}_{char,int,...}($var)
586 should be used. (Refer to stapfuncs(5) for more details.)
587 $return
589 is available in return probes only for functions that are de‐
590 clared with a return value, which can be determined using @de‐
591 fined($return).
592 $var[N]
594 indexes into an array. The index given with a literal number or
595 even an arbitrary numeric expression.
596 A number of operators exist for such basic context variable expres‐
598 sions:
599 $$vars expands to a character string that is equivalent to
601 sprintf("parm1=%x ... parmN=%x var1=%x ... varN=%x",
603 parm1, ..., parmN, var1, ..., varN)
604 for each variable in scope at the probe point. Some values may
606 be printed as =? if their run-time location cannot be found.
607 $$locals
609 expands to a subset of $$vars for only local variables.
610 $$parms
612 expands to a subset of $$vars for only function parameters.
613 $$return
615 is available in return probes only. It expands to a string that
616 is equivalent to sprintf("return=%x", $return) if the probed
617 function has a return value, or else an empty string.
618 & $EXPR
620 expands to the address of the given context variable expression,
621 if it is addressable.
622 @defined($EXPR)
624 expands to 1 or 0 iff the given context variable expression is
625 resolvable, for use in conditionals such as
626 @defined($foo->bar) ? $foo->bar : 0
628 @probewrite($VAR)
631 see the PROBES section of stap(1).
632 $EXPR$ expands to a string with all of $EXPR's members, equivalent to
634 sprintf("{.a=%i, .b=%u, .c={...}, .d=[...]}",
636 $EXPR->a, $EXPR->b)
637 $EXPR$$
640 expands to a string with all of $var's members and submembers,
641 equivalent to
642 sprintf("{.a=%i, .b=%u, .c={.x=%p, .y=%c}, .d=[%i, ...]}",
644 $EXPR->a, $EXPR->b, $EXPR->c->x, $EXPR->c->y, $EXPR->d[0])
645 @errno expands to the last value the C library global variable errno
648 was set to.
649 MORE ON RETURN PROBES
652 For the kernel ".return" probes, only a certain fixed number of returns
653 may be outstanding. The default is a relatively small number, on the
654 order of a few times the number of physical CPUs. If many different
655 threads concurrently call the same blocking function, such as futex(2)
656 or read(2), this limit could be exceeded, and skipped "kretprobes"
657 would be reported by "stap -t". To work around this, specify a
658 probe FOO.return.maxactive(NNN)
660 suffix, with a large enough NNN to cover all expected concurrently
662 blocked threads. Alternately, use the
663 stap -DKRETACTIVE=NNNN
665 stap command line macro setting to override the default for all ".re‐
667 turn" probes.
668 For ".return" probes, context variables other than the "$return" may be
671 accessible, as a convenience for a script programmer wishing to access
672 function parameters. These values are snapshots taken at the time of
673 function entry. (Local variables within the function are not generally
674 accessible, since those variables did not exist in allocated/initial‐
675 ized form at the snapshot moment.) These entry-snapshot variables
676 should be accessed via @entry($var).
677 In addition, arbitrary entry-time expressions can also be saved for
679 ".return" probes using the @entry(expr) operator. For example, one can
680 compute the elapsed time of a function:
681 probe kernel.function("do_filp_open").return {
683 println( get_timeofday_us() - @entry(get_timeofday_us()) )
684 }
685 The following table summarizes how values related to a function parame‐
689 ter context variable, a pointer named addr, may be accessed from a .re‐
690 turn probe.
691 at-entry value past-exit value
693 $addr not available
695 $addr->x->y @cast(@entry($addr),"struct zz")->x->y
696 $addr[0] {kernel,user}_{char,int,...}(& $addr[0])
697 DWARFLESS
701 In absence of debugging information, entry & exit points of kernel &
702 module functions can be probed using the "kprobe" family of probes.
703 However, these do not permit looking up the arguments / local variables
704 of the function. Following constructs are supported :
705 kprobe.function(FUNCTION)
707 kprobe.function(FUNCTION).call
708 kprobe.function(FUNCTION).return
709 kprobe.module(NAME).function(FUNCTION)
710 kprobe.module(NAME).function(FUNCTION).call
711 kprobe.module(NAME).function(FUNCTION).return
712 kprobe.statement(ADDRESS).absolute
713 Probes of type function are recommended for kernel functions, whereas
716 probes of type module are recommended for probing functions of the
717 specified module. In case the absolute address of a kernel or module
718 function is known, statement probes can be utilized.
719 Note that FUNCTION and MODULE names must not contain wildcards, or the
721 probe will not be registered. Also, statement probes must be run under
722 guru-mode only.
723 USER-SPACE
727 Support for user-space probing is available for kernels that are con‐
728 figured with the utrace extensions, or have the uprobes facility in
729 linux 3.5. (Various kernel build configuration options need to be en‐
730 abled; systemtap will advise if these are missing.)
731 There are several forms. First, a non-symbolic probe point:
734 process(PID).statement(ADDRESS).absolute
736 is analogous to kernel.statement(ADDRESS).absolute in that both use raw
738 (unverified) virtual addresses and provide no $variables. The target
739 PID parameter must identify a running process, and ADDRESS should iden‐
740 tify a valid instruction address. All threads of that process will be
741 probed.
742 Second, non-symbolic user-kernel interface events handled by utrace may
744 be probed:
745 process(PID).begin
747 process("FULLPATH").begin
748 process.begin
749 process(PID).thread.begin
750 process("FULLPATH").thread.begin
751 process.thread.begin
752 process(PID).end
753 process("FULLPATH").end
754 process.end
755 process(PID).thread.end
756 process("FULLPATH").thread.end
757 process.thread.end
758 process(PID).syscall
759 process("FULLPATH").syscall
760 process.syscall
761 process(PID).syscall.return
762 process("FULLPATH").syscall.return
763 process.syscall.return
764 process(PID).insn
765 process("FULLPATH").insn
766 process(PID).insn.block
767 process("FULLPATH").insn.block
768 A process.begin probe gets called when new process described by PID or
772 FULLPATH gets created. In addition, it is called once from the context
773 of each preexisting process, at systemtap script startup. This is use‐
774 ful to track live processes. A process.thread.begin probe gets called
775 when a new thread described by PID or FULLPATH gets created. A
776 process.end probe gets called when process described by PID or FULLPATH
777 dies. A process.thread.end probe gets called when a thread described
778 by PID or FULLPATH dies. A process.syscall probe gets called when a
779 thread described by PID or FULLPATH makes a system call. The system
780 call number is available in the $syscall context variable, and the
781 first 6 arguments of the system call are available in the $argN (ex.
782 $arg1, $arg2, ...) context variable. A process.syscall.return probe
783 gets called when a thread described by PID or FULLPATH returns from a
784 system call. The system call number is available in the $syscall con‐
785 text variable, and the return value of the system call is available in
786 the $return context variable. A process.insn probe gets called for ev‐
787 ery single-stepped instruction of the process described by PID or FULL‐
788 PATH. A process.insn.block probe gets called for every block-stepped
789 instruction of the process described by PID or FULLPATH.
790 If a process probe is specified without a PID or FULLPATH, all user
793 threads will be probed. However, if systemtap was invoked with the -c
794 or -x options, then process probes are restricted to the process hier‐
795 archy associated with the target process. If a process probe is un‐
796 specified (i.e. without a PID or FULLPATH), but with the -c option, the
797 PATH of the -c cmd will be heuristically filled into the process PATH.
798 In that case, only command parameters are allowed in the -c command
799 (i.e. no command substitution allowed and no occurrences of any of
800 these characters: '|&;<>(){}').
801 Third, symbolic static instrumentation compiled into programs and
804 shared libraries may be probed:
805 process("PATH").mark("LABEL")
807 process("PATH").provider("PROVIDER").mark("LABEL")
808 process(PID).mark("LABEL")
809 process(PID).provider("PROVIDER").mark("LABEL")
810 A .mark probe gets called via a static probe which is defined in the
813 application by STAP_PROBE1(PROVIDER,LABEL,arg1), which are macros de‐
814 fined in sys/sdt.h. The PROVIDER is an arbitrary application identifi‐
815 er, LABEL is the marker site identifier, and arg1 is the integer-typed
816 argument. STAP_PROBE1 is used for probes with 1 argument, STAP_PROBE2
817 is used for probes with 2 arguments, and so on. The arguments of the
818 probe are available in the context variables $arg1, $arg2, ... An al‐
819 ternative to using the STAP_PROBE macros is to use the dtrace script to
820 create custom macros. Additionally, the variables $$name and
821 $$provider are available as parts of the probe point name. The
822 sys/sdt.h macro names DTRACE_PROBE* are available as aliases for
823 STAP_PROBE*.
824 Finally, full symbolic source-level probes in user-space programs and
827 shared libraries are supported. These are exactly analogous to the
828 symbolic DWARF-based kernel/module probes described above. They expose
829 the same sorts of context $variables for function parameters, local
830 variables, and so on.
831 process("PATH").function("NAME")
833 process("PATH").statement("*@FILE.c:123")
834 process("PATH").plt("NAME")
835 process("PATH").library("PATH").plt("NAME")
836 process("PATH").library("PATH").function("NAME")
837 process("PATH").library("PATH").statement("*@FILE.c:123")
838 process("PATH").function("*").return
839 process("PATH").function("myfun").label("foo")
840 process("PATH").function("foo").callee("bar")
841 process("PATH").plt("NAME").return
842 process(PID).function("NAME")
843 process(PID).statement("*@FILE.c:123")
844 process(PID).plt("NAME")
845 Note that for all process probes, PATH names refer to executables that
849 are searched the same way shells do: relative to the working directory
850 if they contain a "/" character, otherwise in $PATH. If PATH names re‐
851 fer to scripts, the actual interpreters (specified in the script in the
852 first line after the #! characters) are probed.
853 Tapset process probes placed in the special directory $pre‐
856 fix/share/systemtap/tapset/PATH/ with relative paths will have their
857 process parameter prefixed with the location of the tapset. For exam‐
858 ple,
859 process("foo").function("NAME")
862 expands to
865 process("/usr/bin/foo").function("NAME")
867 when placed in $prefix/share/systemtap/tapset/PATH/usr/bin/
871 If PATH is a process component parameter referring to shared libraries
874 then all processes that map it at runtime would be selected for prob‐
875 ing. If PATH is a library component parameter referring to shared li‐
876 braries then the process specified by the process component would be
877 selected. Note that the PATH pattern in a library component will al‐
878 ways apply to libraries statically determined to be in use by the
879 process. However, you may also specify the full path to any library
880 file even if not statically needed by the process.
881 A .plt probe will probe functions in the program linkage table corre‐
884 sponding to the rest of the probe point. .plt can be specified as a
885 shorthand for .plt("*"). The symbol name is available as a $$name con‐
886 text variable; function arguments are not available, since PLTs are
887 processed without debuginfo. A .plt.return probe places a probe at the
888 moment after the return from the named function.
889 If the PATH string contains wildcards as in the MPATTERN case, then
892 standard globbing is performed to find all matching paths. In this
893 case, the $PATH environment variable is not used.
894 If systemtap was invoked with the -c or -x options, then process probes
897 are restricted to the process hierarchy associated with the target
898 process.
899 JAVA
902 Support for probing Java methods is available using Byteman as a back‐
903 end. Byteman is an instrumentation tool from the JBoss project which
904 systemtap can use to monitor invocations for a specific method or line
905 in a Java program.
906 Systemtap does so by generating a Byteman script listing the probes to
908 instrument and then invoking the Byteman bminstall utility.
909 This Java instrumentation support is currently a prototype feature with
911 major limitations. Moreover, Java probing currently does not work
912 across users; the stap script must run (with appropriate permissions)
913 under the same user that the Java process being probed. (Thus a stap
914 script under root currently cannot probe Java methods in a non-root-us‐
915 er Java process.)
916 The first probe type refers to Java processes by the name of the Java
919 process:
920 java("PNAME").class("CLASSNAME").method("PATTERN")
922 java("PNAME").class("CLASSNAME").method("PATTERN").return
923 The PNAME argument must be a pre-existing jvm pid, and be identifiable
925 via a jps listing.
926 The PATTERN parameter specifies the signature of the Java method to
928 probe. The signature must consist of the exact name of the method, fol‐
929 lowed by a bracketed list of the types of the arguments, for instance
930 "myMethod(int,double,Foo)". Wildcards are not supported.
931 The probe can be set to trigger at a specific line within the method by
933 appending a line number with colon, just as in other types of probes:
934 "myMethod(int,double,Foo):245".
935 The CLASSNAME parameter identifies the Java class the method belongs
937 to, either with or without the package qualification. By default, the
938 probe only triggers on descendants of the class that do not override
939 the method definition of the original class. However, CLASSNAME can
940 take an optional caret prefix, as in ^org.my.MyClass, which specifies
941 that the probe should also trigger on all descendants of MyClass that
942 override the original method. For instance, every method with signature
943 foo(int) in program org.my.MyApp can be probed at once using
944 java("org.my.MyApp").class("^java.lang.Object").method("foo(int)")
946 The second probe type works analogously, but refers to Java processes
949 by PID:
950 java(PID).class("CLASSNAME").method("PATTERN")
952 java(PID).class("CLASSNAME").method("PATTERN").return
953 (PIDs for an already running process can be obtained using the jps(1)
955 utility.)
956 Context variables defined within java probes include $arg1 through
958 $arg10 (for up to the first 10 arguments of a method), represented as
959 character-pointers for the toString() form of each actual argument.
960 The arg1 through arg10 script variables provide access to these as or‐
961 dinary strings, fetched via user_string_warn().
962 Prior to systemtap version 3.1, $arg1 through $arg10 could contain ei‐
964 ther integers or character pointers, depending on the types of the ob‐
965 jects being passed to each particular java method. This previous be‐
966 haviour may be invoked with the stap --compatible=3.0 flag.
967 PROCFS
970 These probe points allow procfs "files" in /proc/systemtap/MODNAME to
971 be created, read and written using a permission that may be modified
972 using the proper umask value. Default permissions are 0400 for read
973 probes, and 0200 for write probes. If both a read and write probe are
974 being used on the same file, a default permission of 0600 will be used.
975 Using procfs.umask(0040).read would result in a 0404 permission set for
976 the file. (MODNAME is the name of the systemtap module). The proc
977 filesystem is a pseudo-filesystem which is used as an interface to ker‐
978 nel data structures. There are several probe point variants supported
979 by the translator:
980 procfs("PATH").read
983 procfs("PATH").umask(UMASK).read
984 procfs("PATH").read.maxsize(MAXSIZE)
985 procfs("PATH").umask(UMASK).maxsize(MAXSIZE)
986 procfs("PATH").write
987 procfs("PATH").umask(UMASK).write
988 procfs.read
989 procfs.umask(UMASK).read
990 procfs.read.maxsize(MAXSIZE)
991 procfs.umask(UMASK).read.maxsize(MAXSIZE)
992 procfs.write
993 procfs.umask(UMASK).write
994 Note that there are a few differences when procfs probes are used in
997 the stapbpf runtime. FIFO special files are used instead of proc
998 filesystem files. These files are created in /var/tmp/systemtap-US‐
999 ER/MODNAME. (USER is the name of the user). Additionally, users can‐
1000 not create both read and write probes on the same file.
1001 PATH is the file name (relative to /proc/systemtap/MODNAME or
1003 /var/tmp/systemtap-USER/MODNAME) to be created. If no PATH is speci‐
1004 fied (as in the last two variants above), PATH defaults to "command".
1005 The file name "__stdin" is used internally by systemtap for input
1006 probes and should not be used as a PATH for procfs probes; see the in‐
1007 put probe section below.
1008 When a user reads /proc/systemtap/MODNAME/PATH (normal runtime) or
1010 /var/tmp/systemtap-USER/MODNAME (stapbpf runtime), the corresponding
1011 procfs read probe is triggered. The string data to be read should be
1012 assigned to a variable named $value, like this:
1013 procfs("PATH").read { $value = "100\n" }
1016 When a user writes into /proc/systemtap/MODNAME/PATH (normal runtime)
1019 or /var/tmp/systemtap-USER/MODNAME (stapbpf runtime), the corresponding
1020 procfs write probe is triggered. The data the user wrote is available
1021 in the string variable named $value, like this:
1022 procfs("PATH").write { printf("user wrote: %s", $value) }
1025 MAXSIZE is the size of the procfs read buffer. Specifying MAXSIZE al‐
1028 lows larger procfs output. If no MAXSIZE is specified, the procfs read
1029 buffer defaults to STP_PROCFS_BUFSIZE (which defaults to MAXSTRINGLEN,
1030 the maximum length of a string). If setting the procfs read buffers
1031 for more than one file is needed, it may be easiest to override the
1032 STP_PROCFS_BUFSIZE definition. Here's an example of using MAXSIZE:
1033 procfs.read.maxsize(1024) {
1036 $value = "long string..."
1037 $value .= "another long string..."
1038 $value .= "another long string..."
1039 $value .= "another long string..."
1040 }
1041 INPUT
1045 These probe points make input from stdin available to the script during
1046 runtime. The translator currently supports two variants of this fami‐
1047 ly:
1048 input.char
1050 input.line
1051 input.char is triggered each time a character is read from stdin. The
1054 current character is available in the string variable named char.
1055 There is no newline buffering; the next character is read from stdin as
1056 soon as it becomes available.
1057 input.line causes all characters read from stdin to be buffered until a
1059 newline is read, at which point the probe will be triggered. The cur‐
1060 rent line of characters (including the newline) is made available in a
1061 string variable named line. Note that no more than MAXSTRINGLEN char‐
1062 acters will be buffered. Any additional characters will not be included
1063 in line.
1064 Input probes are aliases for procfs("__stdin").write. Systemtap recon‐
1067 figures stdin if the presence of this procfs probe is detected, there‐
1068 fore "__stdin" should not be used as a path argument for procfs probes.
1069 Additionally, input probes will not work with the -F and --remote op‐
1070 tions.
1071 NETFILTER HOOKS
1074 These probe points allow observation of network packets using the net‐
1075 filter mechanism. A netfilter probe in systemtap corresponds to a net‐
1076 filter hook function in the original netfilter probes API. It is proba‐
1077 bly more convenient to use tapset::netfilter(3stap), which wraps the
1078 primitive netfilter hooks and does the work of extracting useful infor‐
1079 mation from the context variables.
1080 There are several probe point variants supported by the translator:
1083 netfilter.hook("HOOKNAME").pf("PROTOCOL_F")
1086 netfilter.pf("PROTOCOL_F").hook("HOOKNAME")
1087 netfilter.hook("HOOKNAME").pf("PROTOCOL_F").priority("PRIORITY")
1088 netfilter.pf("PROTOCOL_F").hook("HOOKNAME").priority("PRIORITY")
1089 PROTOCOL_F is the protocol family to listen for, currently one of NF‐
1093 PROTO_IPV4, NFPROTO_IPV6, NFPROTO_ARP, or NFPROTO_BRIDGE.
1094 HOOKNAME is the point, or 'hook', in the protocol stack at which to in‐
1097 tercept the packet. The available hook names for each protocol family
1098 are taken from the kernel header files <linux/netfilter_ipv4.h>, <lin‐
1099 ux/netfilter_ipv6.h>, <linux/netfilter_arp.h> and <linux/netfil‐
1100 ter_bridge.h>. For instance, allowable hook names for NFPROTO_IPV4 are
1101 NF_INET_PRE_ROUTING, NF_INET_LOCAL_IN, NF_INET_FORWARD, NF_INET_LO‐
1102 CAL_OUT, and NF_INET_POST_ROUTING.
1103 PRIORITY is an integer priority giving the order in which the probe
1106 point should be triggered relative to any other netfilter hook func‐
1107 tions which trigger on the same packet. Hook functions execute on each
1108 packet in order from smallest priority number to largest priority num‐
1109 ber. If no PRIORITY is specified (as in the first two probe point vari‐
1110 ants above), PRIORITY defaults to "0".
1111 There are a number of predefined priority names of the form NF_IP_PRI_*
1113 and NF_IP6_PRI_* which are defined in the kernel header files <lin‐
1114 ux/netfilter_ipv4.h> and <linux/netfilter_ipv6.h> respectively. The
1115 script is permitted to use these instead of specifying an integer pri‐
1116 ority. (The probe points for NFPROTO_ARP and NFPROTO_BRIDGE currently
1117 do not expose any named hook priorities to the script writer.) Thus,
1118 allowable ways to specify the priority include:
1119 priority("255")
1122 priority("NF_IP_PRI_SELINUX_LAST")
1123 A script using guru mode is permitted to specify any identifier or num‐
1126 ber as the parameter for hook, pf, and priority. This feature should be
1127 used with caution, as the parameter is inserted verbatim into the C
1128 code generated by systemtap.
1129 The netfilter probe points define the following context variables:
1131 $hooknum
1133 The hook number.
1134 $skb The address of the sk_buff struct representing the packet. See
1136 <linux/skbuff.h> for details on how to use this struct, or al‐
1137 ternatively use the tapset tapset::netfilter(3stap) for easy ac‐
1138 cess to key information.
1139 $in The address of the net_device struct representing the network
1142 device on which the packet was received (if any). May be 0 if
1143 the device is unknown or undefined at that stage in the protocol
1144 stack.
1145 $out The address of the net_device struct representing the network
1148 device on which the packet will be sent (if any). May be 0 if
1149 the device is unknown or undefined at that stage in the protocol
1150 stack.
1151 $verdict
1154 (Guru mode only.) Assigning one of the verdict values defined in
1155 <linux/netfilter.h> to this variable alters the further progress
1156 of the packet through the protocol stack. For instance, the fol‐
1157 lowing guru mode script forces all ipv6 network packets to be
1158 dropped:
1159 probe netfilter.pf("NFPROTO_IPV6").hook("NF_IP6_PRE_ROUTING") {
1162 $verdict = 0 /* nf_drop */
1163 }
1164 For convenience, unlike the primitive probe points discussed
1167 here, the probes defined in tapset::netfilter(3stap) export the
1168 lowercase names of the verdict constants (e.g. NF_DROP becomes
1169 nf_drop) as local variables.
1170 KERNEL TRACEPOINTS
1173 This family of probe points hooks up to static probing tracepoints in‐
1174 serted into the kernel or modules. As with markers, these tracepoints
1175 are special macro calls inserted by kernel developers to make probing
1176 faster and more reliable than with DWARF-based probes, and DWARF debug‐
1177 ging information is not required to probe tracepoints. Tracepoints
1178 have an extra advantage of more strongly-typed parameters than markers.
1179 Tracepoint probes look like: kernel.trace("name"). The tracepoint name
1181 string, which may contain the usual wildcard characters, is matched
1182 against the names defined by the kernel developers in the tracepoint
1183 header files. To restrict the search to specific subsystems (e.g.
1184 sched, ext3, etc...), the following syntax can be used: ker‐
1185 nel.trace("system:name"). The tracepoint system string may also con‐
1186 tain the usual wildcard characters.
1187 The handler associated with a tracepoint-based probe may read the op‐
1189 tional parameters specified at the macro call site. These are named
1190 according to the declaration by the tracepoint author. For example,
1191 the tracepoint probe kernel.trace("sched:sched_switch") provides the
1192 parameters $prev and $next. If the parameter is a complex type, as in
1193 a struct pointer, then a script can access fields with the same syntax
1194 as DWARF $target variables. Also, tracepoint parameters cannot be mod‐
1195 ified, but in guru-mode a script may modify fields of parameters.
1196 The subsystem and name of the tracepoint are available in $$system and
1198 $$name and a string of name=value pairs for all parameters of the tra‐
1199 cepoint is available in $$vars or $$parms.
1200 KERNEL MARKERS (OBSOLETE)
1203 This family of probe points hooks up to an older style of static prob‐
1204 ing markers inserted into older kernels or modules. These markers are
1205 special STAP_MARK macro calls inserted by kernel developers to make
1206 probing faster and more reliable than with DWARF-based probes. Fur‐
1207 ther, DWARF debugging information is not required to probe markers.
1208 Marker probe points begin with kernel. The next part names the marker
1210 itself: mark("name"). The marker name string, which may contain the
1211 usual wildcard characters, is matched against the names given to the
1212 marker macros when the kernel and/or module was compiled. Optional‐
1213 ly, you can specify format("format"). Specifying the marker format
1214 string allows differentiation between two markers with the same name
1215 but different marker format strings.
1216 The handler associated with a marker-based probe may read the optional
1218 parameters specified at the macro call site. These are named $arg1
1219 through $argNN, where NN is the number of parameters supplied by the
1220 macro. Number and string parameters are passed in a type-safe manner.
1221 The marker format string associated with a marker is available in $for‐
1223 mat. And also the marker name string is available in $name.
1224 HARDWARE BREAKPOINTS
1227 This family of probes is used to set hardware watchpoints for a given
1228 (global) kernel symbol. The probes take three components as inputs :
1229 1. The virtual address / name of the kernel symbol to be traced is sup‐
1231 plied as argument to this class of probes. ( Probes for only data seg‐
1232 ment variables are supported. Probing local variables of a function
1233 cannot be done.)
1234 2. Nature of access to be probed : a. .write probe gets triggered when
1236 a write happens at the specified address/symbol name. b. rw probe is
1237 triggered when either a read or write happens.
1238 3. .length (optional) Users have the option of specifying the address
1240 interval to be probed using "length" constructs. The user-specified
1241 length gets approximated to the closest possible address length that
1242 the architecture can support. If the specified length exceeds the lim‐
1243 its imposed by architecture, an error message is flagged and probe reg‐
1244 istration fails. Wherever 'length' is not specified, the translator
1245 requests a hardware breakpoint probe of length 1. It should be noted
1246 that the "length" construct is not valid with symbol names.
1247 Following constructs are supported :
1249 probe kernel.data(ADDRESS).write
1251 probe kernel.data(ADDRESS).rw
1252 probe kernel.data(ADDRESS).length(LEN).write
1253 probe kernel.data(ADDRESS).length(LEN).rw
1254 probe kernel.data("SYMBOL_NAME").write
1255 probe kernel.data("SYMBOL_NAME").rw
1256 This set of probes make use of the debug registers of the processor,
1259 which is a scarce resource. (4 on x86 , 1 on powerpc ) The script
1260 translation flags a warning if a user requests more hardware breakpoint
1261 probes than the limits set by architecture. For example,a pass-2 warn‐
1262 ing is flashed when an input script requests 5 hardware breakpoint
1263 probes on an x86 system while x86 architecture supports a maximum of 4
1264 breakpoints. Users are cautioned to set probes judiciously.
1265 PERF
1268 This family of probe points interfaces to the kernel "perf event" in‐
1269 frastructure for controlling hardware performance counters. The events
1270 being attached to are described by the "type", "config" fields of the
1271 perf_event_attr structure, and are sampled at an interval governed by
1272 the "sample_period" and "sample_freq" fields.
1273 These fields are made available to systemtap scripts using the follow‐
1275 ing syntax:
1276 probe perf.type(NN).config(MM).sample(XX)
1278 probe perf.type(NN).config(MM).hz(XX)
1279 probe perf.type(NN).config(MM)
1280 probe perf.type(NN).config(MM).process("PROC")
1281 probe perf.type(NN).config(MM).counter("COUNTER")
1282 probe perf.type(NN).config(MM).process("PROC").counter("NAME")
1283 The systemtap probe handler is called once per XX increments of the un‐
1285 derlying performance counter when using the .sample field or at a fre‐
1286 quency in hertz when using the .hz field. When not specified, the de‐
1287 fault behavior is to sample at a count of 1000000. The range of valid
1288 type/config is described by the perf_event_open(2) system call, and/or
1289 the linux/perf_event.h file. Invalid combinations or exhausted hard‐
1290 ware counter resources result in errors during systemtap script start‐
1291 up. Systemtap does not sanity-check the values: it merely passes them
1292 through to the kernel for error- and safety-checking. By default the
1293 perf event probe is systemwide unless .process is specified, which will
1294 bind the probe to a specific task. If the name is omitted then it is
1295 inferred from the stap -c argument. A perf event can be read on de‐
1296 mand using .counter. The body of the perf probe handler will not be
1297 invoked for a .counter probe; instead, the counter is read in a user
1298 space probe via:
1299 process("PROC").statement("func@file") {stat <<< @perf("NAME")}
1301 PYTHON
1305 Support for probing python 2 and python 3 function is available with
1306 the help of an extra python support module. Note that the debuginfo for
1307 the version of python being probed is required. To run a python script
1308 with the extra python support module you'd add the '-m HelperSDT' op‐
1309 tion to your python command, like this:
1310 stap foo.stp -c "python -m HelperSDT foo.py"
1312 Python probes look like the following:
1314 python2.module("MPATTERN").function("PATTERN")
1316 python2.module("MPATTERN").function("PATTERN").call
1317 python2.module("MPATTERN").function("PATTERN").return
1318 python3.module("MPATTERN").function("PATTERN")
1319 python3.module("MPATTERN").function("PATTERN").call
1320 python3.module("MPATTERN").function("PATTERN").return
1321 The list above includes multiple variants and modifiers which provide
1323 additional functionality or filters. They are:
1324 .function
1326 Places a probe at the beginning of the named function by
1327 default, unless modified by PATTERN. Parameters are
1328 available as context variables.
1329 .call Places a probe at the beginning of the named function.
1331 Parameters are available as context variables.
1332 .return
1334 Places a probe at the moment before the return from the
1335 named function. Parameters and local/global python vari‐
1336 ables are available as context variables.
1337 PATTERN stands for a string literal that aims to identify a point in
1339 the python program. It is made up of three parts:
1340 · The first part is the name of a function (e.g. "foo") or class
1342 method (e.g. "bar.baz"). This part may use the "*" and "?" wild‐
1343 carding operators to match multiple names.
1344 · The second part is optional and begins with the "@" character. It
1346 is followed by the path to the source file containing the function,
1347 which may include a wildcard pattern. The python path is searched
1348 for a matching filename.
1349 · Finally, the third part is optional if the file name part was giv‐
1351 en, and identifies the line number in the source file preceded by a
1352 ":" or a "+". The line number is assumed to be an absolute line
1353 number if preceded by a ":", or relative to the declaration line of
1354 the function if preceded by a "+". All the lines in the function
1355 can be matched with ":*". A range of lines x through y can be
1356 matched with ":x-y". Ranges and specific lines can be mixed using
1357 commas, e.g. ":x,y-z".
1358 In the above list of probe points, MPATTERN stands for a python module
1360 or script name that names the python module of interest. This part may
1361 use the "*" and "?" wildcarding operators to match multiple names. The
1362 python path is searched for a matching filename.
1363
1367 Here are some example probe points, defining the associated events.
1368 begin, end, end
1370 refers to the startup and normal shutdown of the session. In
1371 this case, the handler would run once during startup and twice
1372 during shutdown.
1373 timer.jiffies(1000).randomize(200)
1375 refers to a periodic interrupt, every 1000 +/- 200 jiffies.
1376 kernel.function("*init*"), kernel.function("*exit*")
1378 refers to all kernel functions with "init" or "exit" in the
1379 name.
1380 kernel.function("*@kernel/time.c:240")
1382 refers to any functions within the "kernel/time.c" file that
1383 span line 240. Note that this is not a probe at the statement
1384 at that line number. Use the kernel.statement probe instead.
1385 kernel.trace("sched_*")
1387 refers to all scheduler-related (really, prefixed) tracepoints
1388 in the kernel.
1389 kernel.mark("getuid")
1391 refers to an obsolete STAP_MARK(getuid, ...) macro call in the
1392 kernel.
1393 module("usb*").function("*sync*").return
1395 refers to the moment of return from all functions with "sync" in
1396 the name in any of the USB drivers.
1397 kernel.statement(0xc0044852)
1399 refers to the first byte of the statement whose compiled in‐
1400 structions include the given address in the kernel.
1401 kernel.statement("*@kernel/time.c:296")
1403 refers to the statement of line 296 within "kernel/time.c".
1404 kernel.statement("bio_init@fs/bio.c+3")
1406 refers to the statement at line bio_init+3 within "fs/bio.c".
1407 kernel.data("pid_max").write
1409 refers to a hardware breakpoint of type "write" set on pid_max
1410 syscall.*.return
1412 refers to the group of probe aliases with any name in the third
1413 position
1414
1417 stap(1),
1418 probe::*[24m(3stap),
1419 tapset::*[24m(3stap)
1420 STAPPROBES(3stap)