1STAP(1) General Commands Manual STAP(1)
2
6 stap - systemtap script translator/driver
7
11 stap [ OPTIONS ] FILENAME [ ARGUMENTS ]
12 stap [ OPTIONS ] - [ ARGUMENTS ]
13 stap [ OPTIONS ] -e SCRIPT [ ARGUMENTS ]
14
17 The stap program is the front-end to the Systemtap tool. It accepts
18 probing instructions (written in a simple scripting language), trans‐
19 lates those instructions into C code, compiles this C code, and loads
20 the resulting kernel module into a running Linux kernel to perform the
21 requested system trace/probe functions. You can supply the script in a
22 named file, from standard input, or from the command line. The program
23 runs until it is interrupted by the user, or if the script voluntarily
24 invokes the exit() function, or by sufficient number of soft errors.
25 The language, which is described in a later section, is strictly typed,
27 declaration free, procedural, and inspired by awk. It allows source
28 code points or events in the kernel to be associated with handlers,
29 which are subroutines that are executed synchronously. It is somewhat
30 similar conceptually to "breakpoint command lists" in the gdb debugger.
31 This manual corresponds to version 0.6.2.
33
36 The systemtap translator supports the following options. Any other
37 option prints a list of supported options.
38 -v Increase verbosity. Produce a larger volume of informative (?)
40 output each time option repeated.
41 -h Show help message.
43 -V Show version message.
45 -k Keep the temporary directory after all processing. This may be
47 useful in order to examine the generated C code, or to reuse the
48 compiled kernel object.
49 -g Guru mode. Enable parsing of unsafe expert-level constructs
51 like embedded C.
52 -P Prologue-searching mode. Activate heuristics to work around
54 incorrect debbugging information for $target variables.
55 -u Unoptimized mode. Disable unused code elision during elabora‐
57 tion.
58 -w Suppressed warnings mode. Disable warning messages for elided
60 code in user script.
61 -b Use bulk mode (percpu files) for kernel-to-user data transfer.
63 -t Collect timing information on the number of times probe executes
65 and average amount of time spent in each probe.
66 -sNUM Use NUM megabyte buffers for kernel-to-user data transfer. On a
68 multiprocessor in bulk mode, this is a per-processor amount.
69 -p NUM Stop after pass NUM. The passes are numbered 1-5: parse, elabo‐
71 rate, translate, compile, run. See the PROCESSING section for
72 details.
73 -I DIR Add the given directory to the tapset search directory. See the
75 description of pass 2 for details.
76 -D NAME=VALUE
78 Add the given C preprocessor directive to the module Makefile.
79 These can be used to override limit parameters described below.
80 -R DIR Look for the systemtap runtime sources in the given directory.
82 -r RELEASE
84 Build for given kernel release instead of currently running one.
85 -m MODULE
87 Use the given name for the generated kernel object module,
88 instead of a unique randomized name. The generated kernel
89 object module is copied to the current directory.
90 -o FILE
92 Send standard output to named file. In bulk mode, percpu files
93 will start with FILE_ followed by the cpu number.
94 -c CMD Start the probes, run CMD, and exit when CMD finishes.
96 -x PID Sets target() to PID. This allows scripts to be written that
98 filter on a specific process.
99
102 Any additional arguments on the command line are passed to the script
103 parser for substitution. See below.
104
107 The systemtap script language resembles awk. There are two main outer‐
108 most constructs: probes and functions. Within these, statements and
109 expressions use C-like operator syntax and precedence.
110 GENERAL SYNTAX
113 Whitespace is ignored. Three forms of comments are supported:
114 # ... shell style, to the end of line, except for $# and @#
115 // ... C++ style, to the end of line
116 /* ... C style ... */
117 Literals are either strings enclosed in double-quotes (passing through
118 the usual C escape codes with backslashes), or integers (in decimal,
119 hexadecimal, or octal, using the same notation as in C). All strings
120 are limited in length to some reasonable value (a few hundred bytes).
121 Integers are 64-bit signed quantities, although the parser also accepts
122 (and wraps around) values above positive 2**63.
123 In addition, script arguments given at the end of the command line may
125 be inserted. Use $1 ... $<NN> for insertion unquoted, @1 ... @<NN> for
126 insertion as a string literal. The number of arguments may be accessed
127 through $# (as an unquoted number) or through @# (as a quoted number).
128 These may be used at any place a token may begin, including within the
129 preprocessing stage. Reference to an argument number beyond what was
130 actually given is an error.
131 PREPROCESSING
134 A simple conditional preprocessing stage is run as a part of parsing.
135 The general form is similar to the cond ? exp1 : exp2 ternary operator:
136 %( CONDITION %? TRUE-TOKENS %)
137 %( CONDITION %? TRUE-TOKENS %: FALSE-TOKENS %)
138 The CONDITION is either an expression whose format is determined by its
139 first keyword, or a string literals comparison or a numeric literals
140 comparison.
141 If the first part is the identifier kernel_vr or kernel_v to refer to
143 the kernel version number, with ("2.6.13-1.322FC3smp") or without
144 ("2.6.13") the release code suffix, then the second part is one of the
145 six standard numeric comparison operators <, <=, ==, !=, >, and >=, and
146 the third part is a string literal that contains an RPM-style version-
147 release value. The condition is deemed satisfied if the version of the
148 target kernel (as optionally overridden by the -r option) compares to
149 the given version string. The comparison is performed by the glibc
150 function strverscmp. As a special case, if the operator is for simple
151 equality (==), or inequality (!=), and the third part contains any
152 wildcard characters (* or ? or [), then the expression is treated as a
153 wildcard (mis)match as evaluated by fnmatch.
154 If, on the other hand, the first part is the identifier arch to refer
156 to the processor architecture, then the second part then the second
157 part is one of the two string comparison operators == or !=, and the
158 third part is a string literal for matching it. This comparison is a
159 wildcard (mis)match.
160 Otherwise, the CONDITION is expected to be a comparison between two
162 string literals or two numeric literals. In this case, the arguments
163 are the only variables usable.
164 The TRUE-TOKENS and FALSE-TOKENS are zero or more general parser tokens
166 (possibly including nested preprocessor conditionals), and are pasted
167 into the input stream if the condition is true or false. For example,
168 the following code induces a parse error unless the target kernel ver‐
169 sion is newer than 2.6.5:
170 %( kernel_v <= "2.6.5" %? **ERROR** %) # invalid token sequence
171 The following code might adapt to hypothetical kernel version drift:
172 probe kernel.function (
173 %( kernel_v <= "2.6.12" %? "__mm_do_fault" %:
174 %( kernel_vr == "2.6.13*smp" %? "do_page_fault" %:
175 UNSUPPORTED %) %)
176 ) { /* ... */ }
177 %( arch == "ia64" %?
179 probe syscall.vliw = kernel.function("vliw_widget") {}
180 %)
181 VARIABLES
184 Identifiers for variables and functions are an alphanumeric sequence,
185 and may include "_" and "$" characters. They may not start with a
186 plain digit, as in C. Each variable is by default local to the probe
187 or function statement block within which it is mentioned, and therefore
188 its scope and lifetime is limited to a particular probe or function in‐
189 vocation.
190 Scalar variables are implicitly typed as either string or integer. As‐
192 sociative arrays also have a string or integer value, and a a tuple of
193 strings and/or integers serving as a key. Here are a few basic expres‐
194 sions.
195 var1 = 5
196 var2 = "bar"
197 array1 [pid()] = "name" # single numeric key
198 array2 ["foo",4,i++] += 5 # vector of string/num/num keys
199 if (["hello",5,4] in array2) println ("yes") # membership test
200 The translator performs type inference on all identifiers, including
202 array indexes and function parameters. Inconsistent type-related use
203 of identifiers signals an error.
204 Variables may be declared global, so that they are shared amongst all
206 probes and live as long as the entire systemtap session. There is one
207 namespace for all global variables, regardless of which script file
208 they are found within. A global declaration may be written at the out‐
209 ermost level anywhere, not within a block of code. The following dec‐
210 laration marks a few variables as global. The translator will infer
211 for each its value type, and if it is used as an array, its key types.
212 Optionally, scalar globals may be initialized with a string or number
213 literal.
214 global var1, var2, var3=4
215 Arrays are limited in size by the MAXMAPENTRIES variable -- see the
217 SAFETY AND SECURITY section for details. Optionally, global arrays may
218 be declared with a maximum size in brackets, overriding MAXMAPENTRIES
219 for that array only. Note that this doesn't indicate the type of keys
220 for the array, just the size.
221 global tiny_array[10], normal_array, big_array[50000]
222 STATEMENTS
225 Statements enable procedural control flow. They may occur within func‐
226 tions and probe handlers. The total number of statements executed in
227 response to any single probe event is limited to some number defined by
228 a macro in the translated C code, and is in the neighbourhood of 1000.
229 EXP Execute the string- or integer-valued expression and throw away
231 the value.
232 { STMT1 STMT2 ... }
234 Execute each statement in sequence in this block. Note that
235 separators or terminators are generally not necessary between
236 statements.
237 ; Null statement, do nothing. It is useful as an optional separa‐
239 tor between statements to improve syntax-error detection and to
240 handle certain grammar ambiguities.
241 if (EXP) STMT1 [ else STMT2 ]
243 Compare integer-valued EXP to zero. Execute the first (non-ze‐
244 ro) or second STMT (zero).
245 while (EXP) STMT
247 While integer-valued EXP evaluates to non-zero, execute STMT.
248 for (EXP1; EXP2; EXP3) STMT
250 Execute EXP1 as initialization. While EXP2 is non-zero, execute
251 STMT, then the iteration expression EXP3.
252 foreach (VAR in ARRAY [ limit EXP ]) STMT
254 Loop over each element of the named global array, assigning cur‐
255 rent key to VAR. The array may not be modified within the
256 statement. By adding a single + or - operator after the VAR or
257 the ARRAY identifier, the iteration will proceed in a sorted or‐
258 der, by ascending or descending index or value. Using the op‐
259 tional limit keyword limits the number of loop iterations to EXP
260 times. EXP is evaluted once at the beginning of the loop.
261 foreach ([VAR1, VAR2, ...] in ARRAY [ limit EXP ]) STMT
263 Same as above, used when the array is indexed with a tuple of
264 keys. A sorting suffix may be used on at most one VAR or ARRAY
265 identifier.
266 break, continue
268 Exit or iterate the innermost nesting loop (while or for or
269 foreach) statement.
270 return EXP
272 Return EXP value from enclosing function. If the function's
273 value is not taken anywhere, then a return statement is not
274 needed, and the function will have a special "unknown" type with
275 no return value.
276 next Return now from enclosing probe handler.
278 delete ARRAY[INDEX1, INDEX2, ...]
280 Remove from ARRAY the element specified by the index tuple. The
281 value will no longer be available, and subsequent iterations
282 will not report the element. It is not an error to delete an
283 element that does not exist.
284 delete ARRAY
286 Remove all elements from ARRAY.
287 delete SCALAR
289 Removes the value of SCALAR. Integers and strings are cleared
290 to 0 and "" respectively, while statistics are reset to the ini‐
291 tial empty state.
292 EXPRESSIONS
295 Systemtap supports a number of operators that have the same general
296 syntax, semantics, and precedence as in C and awk. Arithmetic is per‐
297 formed as per typical C rules for signed integers. Division by zero or
298 overflow is detected and results in an error.
299 binary numeric operators
301 * / % + - >> << & ^ | && ||
302 binary string operators
304 . (string concatenation)
305 numeric assignment operators
307 = *= /= %= += -= >>= <<= &= ^= |=
308 string assignment operators
310 = .=
311 unary numeric operators
313 + - ! ~ ++ --
314 binary numeric or string comparison operators
316 < > <= >= == !=
317 ternary operator
319 cond ? exp1 : exp2
320 grouping operator
322 ( exp )
323 function call
325 fn ([ arg1, arg2, ... ])
326 array membership check
328 exp in array
329 [exp1, exp2, ...] in array
330 PROBES
333 The main construct in the scripting language identifies probes. Probes
334 associate abstract events with a statement block ("probe handler") that
335 is to be executed when any of those events occur. The general syntax
336 is as follows:
337 probe PROBEPOINT [, PROBEPOINT] { [STMT ...] }
338 Events are specified in a special syntax called "probe points". There
340 are several varieties of probe points defined by the translator, and
341 tapset scripts may define further ones using aliases. These are listed
342 in the stapprobes(5) manual pages.
343 The probe handler is interpreted relative to the context of each event.
345 For events associated with kernel code, this context may include vari‐
346 ables defined in the source code at that spot. These "target vari‐
347 ables" are presented to the script as variables whose names are pre‐
348 fixed with "$". They may be accessed only if the kernel's compiler
349 preserved them despite optimization. This is the same constraint that
350 a debugger user faces when working with optimized code. Some other
351 events have very little context.
352 New probe points may be defined using "aliases". Probe point aliases
354 look similar to probe definitions, but instead of activating a probe at
355 the given point, it just defines a new probe point name as an alias to
356 an existing one. There are two types of alias, i.e. the prologue style
357 and the epilogue style which are identified by "=" and "+=" respective‐
358 ly.
359 For prologue style alias, the statement block that follows an alias
361 definition is implicitly added as a prologue to any probe that refers
362 to the alias. While for the epilogue style alias, the statement block
363 that follows an alias definition is implicitly added as an epilogue to
364 any probe that refers to the alias. For example:
365 probe syscall.read = kernel.function("sys_read") {
367 fildes = $fd
368 }
369 defines a new probe point syscall.read, which expands to
370 kernel.function("sys_read"), with the given statement as a prologue.
371 And
372 probe syscall.read += kernel.function("sys_read") {
373 fildes = $fd
374 }
375 defines a new probe point with the given statement as an epilogue.
376 Another probe definition may use the alias like this:
378 probe syscall.read {
379 printf("reading fd=%d0, fildes)
380 }
381 FUNCTIONS
384 Systemtap scripts may define subroutines to factor out common work.
385 Functions take any number of scalar (integer or string) arguments, and
386 must return a single scalar (integer or string). An example function
387 declaration looks like this:
388 function thisfn (arg1, arg2) {
389 return arg1 + arg2
390 }
391 Note the general absence of type declarations, which are instead in‐
392 ferred by the translator. However, if desired, a function definition
393 may include explicit type declarations for its return value and/or its
394 arguments. This is especially helpful for embedded-C functions. In
395 the following example, the type inference engine need only infer type
396 type of arg2 (a string).
397 function thatfn:string (arg1:long, arg2) {
398 return sprint(arg1) . arg2
399 }
400 Functions may call others or themselves recursively, up to a fixed
401 nesting limit. This limit is defined by a macro in the translated C
402 code and is in the neighbourhood of 10.
403 PRINTING
406 There are a set of function names that are specially treated by the
407 translator. They format values for printing to the standard systemtap
408 output stream in a more convenient way. The sprint* variants return
409 the formatted string instead of printing it.
410 print, sprint
412 Print one or more values of any type, concatenated directly to‐
413 gether.
414 println, sprintln
416 Print values like print and sprint, but also append a newline.
417 printd, sprintd
419 Take a string delimiter and two or more values of any type, and
420 print the values with the delimiter interposed. The delimiter
421 must be a literal string constant.
422 printdln, sprintdln
424 Print values with a delimiter like printd and sprintd, but also
425 append a newline.
426 printf, sprintf
428 Take a formatting string and a number of values of corresponding
429 types, and print them all. The format must be a literal string
430 constant.
431 The printf formatting directives similar to those of C, except that
433 they are fully type-checked by the translator.
434 x = sprintf("take %d steps forward, %d steps back\n", 3, 2)
435 printf("take %d steps forward, %d steps back\n", 3+1, 2*2)
436 bob = "bob"
437 alice = "alice"
438 print(bob)
439 print("hello")
440 print(10)
441 printf("%s phoned %s %.4x times\n", bob, alice . bob, 3456)
442 printf("%s except after %s\n",
443 sprintf("%s before %s",
444 sprint(1), sprint(3)),
445 sprint("C"))
446 id[bob] = 1234
447 id[alice] = 5678
448 foreach (name in id)
449 printdln("|", strlen(name), name, id[name])
450 STATISTICS
453 It is often desirable to collect statistics in a way that avoids the
454 penalties of repeatedly exclusive locking the global variables those
455 numbers are being put into. Systemtap provides a solution using a spe‐
456 cial operator to accumulate values, and several pseudo-functions to ex‐
457 tract the statistical aggregates.
458 The aggregation operator is <<<, and resembles an assignment, or a C++
460 output-streaming operation. The left operand specifies a scalar or ar‐
461 ray-index lvalue, which must be declared global. The right operand is
462 a numeric expression. The meaning is intuitive: add the given number
463 to the pile of numbers to compute statistics of. (The specific list of
464 statistics to gather is given separately, by the extraction functions.)
465 foo <<< 1
466 stats[pid()] <<< memsize
467 The extraction functions are also special. For each appearance of a
469 distinct extraction function operating on a given identifier, the
470 translator arranges to compute a set of statistics that satisfy it.
471 The statistics system is thereby "on-demand". Each execution of an ex‐
472 traction function causes the aggregation to be computed for that moment
473 across all processors.
474 Here is the set of extractor functions. The first argument of each is
476 the same style of lvalue used on the left hand side of the accumulate
477 operation. The @count(v), @sum(v), @min(v), @max(v), @avg(v) extractor
478 functions compute the number/total/minimum/maximum/average of all accu‐
479 mulated values. The resulting values are all simple integers.
480 Histograms are also available, but are more complicated because they
482 have a vector rather than scalar value. @hist_linear(v,start,stop,in‐
483 terval) represents a linear histogram from "start" to "stop" by incre‐
484 ments of "interval". The interval must be positive. Similarly,
485 @hist_log(v) represents a base-2 logarithmic histogram. Printing a his‐
486 togram with the print family of functions renders a histogram object as
487 a tabular "ASCII art" bar chart.
488 probe foo {
489 x <<< $value
490 }
491 probe end {
492 printf ("avg %d = sum %d / count %d\n",
493 @avg(x), @sum(x), @count(x))
494 print (@hist_log(v))
495 }
496 EMBEDDED C
499 When in guru mode, the translator accepts embedded code in the script.
500 Such code is enclosed between %{ and %} markers, and is transcribed
501 verbatim, without analysis, in some sequence, into the generated C
502 code. At the outermost level, this may be useful to add #include in‐
503 structions, and any auxiliary definitions for use by other embedded
504 code.
505 The other place where embedded code is permitted is as a function body.
507 In this case, the script language body is replaced entirely by a piece
508 of C code enclosed again between %{ and %} markers. This C code may do
509 anything reasonable and safe. There are a number of undocumented but
510 complex safety constraints on atomicity, concurrency, resource consump‐
511 tion, and run time limits, so this is an advanced technique.
512 The memory locations set aside for input and output values are made
514 available to it using a macro THIS. Here are some examples:
515 function add_one (val) %{
516 THIS->__retvalue = THIS->val + 1;
517 %}
518 function add_one_str (val) %{
519 strlcpy (THIS->__retvalue, THIS->val, MAXSTRINGLEN);
520 strlcat (THIS->__retvalue, "one", MAXSTRINGLEN);
521 %}
522 The function argument and return value types have to be inferred by the
523 translator from the call sites in order for this to work. The user
524 should examine C code generated for ordinary script-language functions
525 in order to write compatible embedded-C ones.
526 BUILT-INS
529 A set of builtin functions and probe point aliases are provided by the
530 scripts installed under the /usr/share/systemtap/tapset directory.
531 These are described in the stapfuncs(5) and stapprobes(5) manual pages.
532
535 The translator begins pass 1 by parsing the given input script, and all
536 scripts (files named *.stp) found in a tapset directory. The directo‐
537 ries listed with -I are processed in sequence, each processed in "guru
538 mode". For each directory, a number of subdirectories are also
539 searched. These subdirectories are derived from the selected kernel
540 version (the -R option), in order to allow more kernel-version-specific
541 scripts to override less specific ones. For example, for a kernel ver‐
542 sion 2.6.12-23.FC3 the following patterns would be searched, in se‐
543 quence: 2.6.12-23.FC3/*.stp, 2.6.12/*.stp, 2.6/*.stp, and finally *.stp
544 Stopping the translator after pass 1 causes it to print the parse
545 trees.
546 In pass 2, the translator analyzes the input script to resolve symbols
549 and types. References to variables, functions, and probe aliases that
550 are unresolved internally are satisfied by searching through the parsed
551 tapset scripts. If any tapset script is selected because it defines an
552 unresolved symbol, then the entirety of that script is added to the
553 translator's resolution queue. This process iterates until all symbols
554 are resolved and a subset of tapset scripts is selected.
555 Next, all probe point descriptions are validated against the wide vari‐
557 ety supported by the translator. Probe points that refer to code loca‐
558 tions ("synchronous probe points") require the appropriate kernel de‐
559 bugging information to be installed. In the associated probe handlers,
560 target-side variables (whose names begin with "$") are found and have
561 their run-time locations decoded.
562 Next, all probes and functions are analyzed for optimization opportuni‐
564 ties, in order to remove variables, expressions, and functions that
565 have no useful value and no side-effect. Embedded-C functions are as‐
566 sumed to have side-effects unless they include the magic string
567 /* pure */. Since this optimization can hide latent code errors such
568 as type mismatches or invalid $target variables, it sometimes may be
569 useful to disable the optimizations with the -u option.
570 Finally, all variable, function, parameter, array, and index types are
572 inferred from context (literals and operators). Stopping the transla‐
573 tor after pass 2 causes it to list all the probes, functions, and vari‐
574 ables, along with all inferred types. Any inconsistent or unresolved
575 types cause an error.
576 In pass 3, the translator writes C code that represents the actions of
579 all selected script files, and creates a Makefile to build that into a
580 kernel object. These files are placed into a temporary directory.
581 Stopping the translator at this point causes it to print the contents
582 of the C file.
583 In pass 4, the translator invokes the Linux kernel build system to cre‐
586 ate the actual kernel object file. This involves running make in the
587 temporary directory, and requires a kernel module build system (head‐
588 ers, config and Makefiles) to be installed in the usual spot /lib/mod‐
589 ules/VERSION/build. Stopping the translator after pass 4 is the last
590 chance before running the kernel object. This may be useful if you
591 want to archive the file.
592 In pass 5, the translator invokes the systemtap auxiliary program
595 staprun program for the given kernel object. This program arranges to
596 load the module then communicates with it, copying trace data from the
597 kernel into temporary files, until the user sends an interrupt signal.
598 Any run-time error encountered by the probe handlers, such as running
599 out of memory, division by zero, exceeding nesting or runtime limits,
600 results in a soft error indication. Soft errors in excess of MAXERRORS
601 block of all subsequent probes, and terminate the session. Finally,
602 staprun unloads the module, and cleans up.
603
606 See the stapex(5) manual page for a collection of samples.
607
610 The systemtap translator caches the pass 3 output (the generated C
611 code) and the pass 4 output (the compiled kernel module) if pass 4 com‐
612 pletes successfully. This cached output is reused if the same script
613 is translated again assuming the same conditions exist (same kernel
614 version, same systemtap version, etc.). Cached files are stored in the
615 $SYSTEMTAP_DIR/cache directory, which may be periodically
616 cleaned/erased by the user.
617
620 Systemtap is an administrative tool. It exposes kernel internal data
621 structures and potentially private user information. It acquires ei‐
622 ther root privileges
623 To actually run the kernel objects it builds, a user must be one of the
625 following:
626 · the root user;
628 · a member of the stapdev group; or
630 · a member of the stapusr group. Members of the stapusr group can
632 only use modules located in the /lib/modules/VERSION/systemtap di‐
633 rectory. This directory must be owned by root and not be world
634 writable.
635 The kernel modules generated by stap program are run by the staprun
637 program. The latter is a part of the Systemtap package, dedicated to
638 module loading and unloading (but only in the white zone), and kernel-
639 to-user data transfer. Since staprun does not perform any additional
640 security checks on the kernel objects it is given, it would be unwise
641 for a system administrator to add untrusted users to the stapdev or
642 stapusr groups.
643 The translator asserts certain safety constraints. It aims to ensure
645 that no handler routine can run for very long, allocate memory, perform
646 unsafe operations, or in unintentionally interfere with the kernel.
647 Use of script global variables is suitably locked to protect against
648 manipulation by concurrent probe handlers. Use of guru mode constructs
649 such as embedded C can violate these constraints, leading to kernel
650 crash or data corruption.
651 The resource use limits are set by macros in the generated C code.
653 These may be overridden with the -D flag. A selection of these is as
654 follows:
655 MAXNESTING
657 Maximum number of recursive function call levels, default 10.
658 MAXSTRINGLEN
660 Maximum length of strings, default 128.
661 MAXTRYLOCK
663 Maximum number of iterations to wait for locks on global vari‐
664 ables before declaring possible deadlock and skipping the probe,
665 default 1000.
666 MAXACTION
668 Maximum number of statements to execute during any single probe
669 hit (with interrupts disabled), default 1000.
670 MAXACTION_INTERRUPTIBLE
672 Maximum number of statements to execute during any single probe
673 hit which is executed with interrupts enabled (such as begin/end
674 probes), default (MAXACTION * 10).
675 MAXMAPENTRIES
677 Maximum number of rows in any single global array, default 2048.
678 MAXERRORS
680 Maximum number of soft errors before an exit is triggered, de‐
681 fault 0, which means that the first error will exit the script.
682 MAXSKIPPED
684 Maximum number of skipped reentrant probes before an exit is
685 triggered, default 100.
686 MINSTACKSPACE
688 Minimum number of free kernel stack bytes required in order to
689 run a probe handler, default 1024. This number should be large
690 enough for the probe handler's own needs, plus a safety margin.
691 Multipule scripts can write data into a relay buffer concurrently. A
694 host script provides an interface for accessing its relay buffer to
695 guest scripts. Then, the output of the guests are merged into the out‐
696 put of the host. To run a script as a host, execute stap with -DRELAY‐
697 HOST[=name] option. The name identifies your host script among several
698 hosts. While running the host, execute stap with -DRELAYGUEST[=name]
699 to add a guest script to the host. Note that you must unload guests
700 before unloading a host. If there are some guests connected to the
701 host, unloading the host will be failed.
702 In case something goes wrong with stap or staprun after a probe has al‐
705 ready started running, one may safely kill both user processes, and re‐
706 move the active probe kernel module with rmmod. Any pending trace mes‐
707 sages may be lost.
708 In addition to the methods outlined above, the generated kernel module
711 also uses overload processing to make sure that probes can't run for
712 too long. If more than STP_OVERLOAD_THRESHOLD cycles (default
713 500000000) have been spent in all the probes on a single cpu during the
714 last STP_OVERLOAD_INTERVAL cycles (default 1000000000), the probes have
715 overloaded the system and an exit is triggered.
716 By default, overload processing is turned on for all modules. If you
718 would like to disable overload processing, define STP_NO_OVERLOAD.
719
722 ~/.systemtap
723 Systemtap data directory for cached systemtap files, unless
724 overridden by the SYSTEMTAP_DIR environment variable.
725 /tmp/stapXXXXXX
727 Temporary directory for systemtap files, including translated C
728 code and kernel object.
729 /usr/share/systemtap/tapset
731 The automatic tapset search directory, unless overridden by the
732 SYSTEMTAP_TAPSET environment variable.
733 /usr/share/systemtap/runtime
735 The runtime sources, unless overridden by the SYSTEMTAP_RUNTIME
736 environment variable.
737 /lib/modules/VERSION/build
739 The location of kernel module building infrastructure.
740 /usr/lib/debug/lib/modules/VERSION
742 The location of kernel debugging information when packaged into
743 the kernel-debuginfo RPM, unless overridden by the SYSTEMTAP_DE‐
744 BUGINFO_PATH environment variable. The default value for this
745 variable is -:.debug:/usr/lib/debug. This path is interpreted
746 by elfutils as a list of base directories of which various sub‐
747 directories will be searched. The - at the front means to skip
748 CRC matching for separated debug objects and is a small perfor‐
749 mance win if no possible corruption is suspected.
750 /usr/bin/staprun
752 The auxiliary program supervising module loading, interaction,
753 and unloading.
754
757 stapprobes(5), stapfuncs(5), stapex(5), awk(1), gdb(1)
758
761 Use the Bugzilla link off of the project web page or our mailing list.
762 http://sources.redhat.com/systemtap/,<systemtap@sources.redhat.com>.
763Red Hat 2008-03-27 STAP(1)