stapprobes(5) - Linux man page

Name

stapprobes - systemtap probe points

Description

The following sections enumerate the variety of probe points supported by the systemtap translator, and additional aliases defined by standard tapset scripts.

The general probe point syntax is a dotted-symbol sequence. This allows a breakdown of the event namespace into parts, somewhat like the Domain Name System does on the Internet. Each component identifier may be parametrized by a string or number literal, with a syntax like a function call. A component may include a "*" character, to expand to other matching probe points. A probe point may be followed by a "?" character, to indicate that it is optional, and that no error should result if it fails to expand. Optionalness passes down through all levels of alias/wildcard expansion.

These are all syntactically valid probe points:

kernel.function("foo").return
syscall(22)
user.inode("/bin/vi").statement(0x2222)
end
syscall.*
kernel.function("no_such_function") ?

Probes may be broadly classified into "synchronous" and "asynchronous". A "synchronous" event is deemed to occur when any processor executes an instruction matched by the specification. This gives these probes a reference point (instruction address) from which more contextual data may be available. Other families of probe points refer to "asynchronous" events such as timers/counters rolling over, where there is no fixed reference point that is related. Each probe point specification may match multiple locations (for example, using wildcards or aliases), and all them are then probed. A probe declaration may also contain several comma-separated specifications, all of which are probed.

BEGIN/END

The probe points begin and end are defined by the translator to refer to the time of session startup and shutdown. All "begin" probe handlers are run, in some sequence, during the startup of the session. All global variables will have been initialized prior to this point. All "end" probes are run, in some sequence, during the normal shutdown of a session, such as in the aftermath of an exit () function call, or an interruption from the user. In the case of an error-triggered shutdown, "end" probes are not run. There are no target variables available in either context. If the order of execution among "begin" or "end" probes is significant, then an optional sequence number may be provided:

begin(N)
end(N)

The number N may be positive or negative. The probe handlers are run in increasing order, and the order between handlers with the same sequence number is unspecified. When "begin" or "end" are given without a sequence, they are effectively sequence zero.

NEVER

The probe point never is specially defined by the translator to mean "never". Its probe handler is never run, though its statements are analyzed for symbol / type correctness as usual. This probe point may be useful in conjunction with optional probes.

TIMERS

Intervals defined by the standard kernel "jiffies" timer may be used to trigger probe handlers asynchronously. Two probe point variants are supported by the translator:

timer.jiffies(N)
timer.jiffies(N).randomize(M)

The probe handler is run every N jiffies (a kernel-defined unit of time, typically between 1 and 60 ms). If the "randomize" component is given, a linearly distributed random value in the range [-M..+M] is added to N every time the handler is run. N is restricted to a reasonable range (1 to around a million), and M is restricted to be smaller than N. There are no target variables provided in either context. It is possible for such probes to be run concurrently on a multi-processor computer. Alternatively, intervals may be specified in units of time. There are two probe point variants similar to the jiffies timer:

timer.ms(N)
timer.ms(N).randomize(M)

Here, N and M are specified in milliseconds, but the full options for units are seconds (s/sec), milliseconds (ms/msec), microseconds (us/usec), nanoseconds (ns/nsec), and hertz (hz). Randomization is not supported for hertz timers. The actual resolution of the timers depends on the target kernel. For kernels prior to 2.6.17, timers are limited to jiffies resolution, so intervals are rounded up to the nearest jiffies interval. After 2.6.17, the implementation uses hrtimers for tighter precision, though the actual resolution will be arch-dependent. In either case, if the "randomize" component is given, then the random value will be added to the interval before any rounding occurs. Profiling timers are also available to provide probes that execute on all CPUs at the rate of the system tick. This probe takes no parameters.

timer.profile

Full context information of the interrupted process is available, making this probe suitable for a time-based sampling profiler.

DWARF

This family of probe points uses symbolic debugging information for the target kernel/module/program, as may be found in unstripped executables, or the separate debuginfo packages. They allow placement of probes logically into the execution path of the target program, by specifying a set of points in the source or object code. When a matching statement executes on any processor, the probe handler is run in that context.
Points in a kernel, which are identified by module, source file, line number, function name, C label name, or some combination of these.

Here is a list of probe point families currently supported. The .function variant places a probe near the beginning of the named function, so that parameters are available as context variables. The .return variant places a probe at the moment of return from the named function, so the return value is available as the "$return" context variable. The .inline modifier for .function filters the results to include only instances of inlined functions. The .call modifier selects the opposite subset. Inline functions do not have an identifiable return point, so .return is not supported on .inline probes. The .statement variant places a probe at the exact spot, exposing those local variables that are visible there.

kernel.function(PATTERN)
kernel.function(PATTERN).call
kernel.function(PATTERN).return
kernel.function(PATTERN).inline
module(MPATTERN).function(PATTERN)
module(MPATTERN).function(PATTERN).call
module(MPATTERN).function(PATTERN).return
module(MPATTERN).function(PATTERN).inline
kernel.statement(PATTERN)
kernel.statement(ADDRESS).absolute
module(MPATTERN).statement(PATTERN)

In the above list, MPATTERN stands for a string literal that aims to identify the loaded kernel module of interest. It may include "*", "[]", and "?" wildcards. PATTERN stands for a string literal that aims to identify a point in the program. It is made up of three parts. The first part is the name of a function, as would appear in the nm program's output. This part may use the "*" and "?" wildcarding operators to match multiple names. The second part is optional, and begins with the "@" character. It is followed by a source file name wildcard pattern, such as mm/slab*. Finally, the third part is optional if the file name part was given, and identifies the line number in the source file, preceded by a ":". As an alternative, PATTERN may be a numeric constant, indicating an (module-relative or kernel-_stext-relative) address. In guru mode only, absolute kernel addresses may be specified with the ".absolute" suffix. Some of the source-level variables, such as function parameters, locals, globals visible in the compilation unit, may be visible to probe handlers. They may refer to these variables by prefixing their name with "$" within the scripts. In addition, a special syntax allows limited traversal of structures, pointers, and arrays.

$var refers to an in-scope variable "var". If it's an integer-like type, it will be cast to a 64-bit int for systemtap script use. String-like pointers (char *) may be copied to systemtap string values using the kernel_string or user_string functions.

$var->field

traversal to a structure's field. The indirection operator may be repeated to follow more levels of pointers.

$var[N]

indexes into an array. The index is given with a literal number.

MARKERS

This family of probe points hooks up to static probing markers inserted into the kernel or modules. These markers are special macro calls inserted by kernel developers to make probing faster and more reliable than with DWARF-based probes. Further, DWARF debugging information is not required to probe markers.
Marker probe points begin with kernel or module("name"), just like DWARF probes. This identifies the source of symbol table used for finding markers. The next part names the marker itself: mark("name"). The marker name string, which may contain the usual wildcard characters, is matched against the names given to the marker macros when the kernel or module was compiled.

The handler associated with a marker-based probe may read the optional parameters specified at the macro call site. These are named $arg1 through $argNN, where NN is the number of parameters supplied by the macro. Number and string parameters are passed in a type-safe manner.

PERFORMANCE MONITORING HARDWARE

The perfmon family of probe points is used to access the performance monitoring hardware available in modern processors. This family of probes points needs the perfmon2 support in the kernel to access the performance monitoring hardware.
Performance monitor hardware points begin with a perfmon. The next part of the names the event being counted counter("event"). The event names are processor implementation specific with the execption of the generic cycles and instructions events, which are available on all processors. This sets up a counter on the processor to count the number of events occuring on the processor. For more details on the performance monitoring events available on a specific processor use the command perfmon2 command:

pfmon -l

$counter

is a handle used in the body of the probe for operations involving the counter associated with the probe.

read_counter

is a function that is passed the handle for the perfmon probe and returns the current count for the event.

Examples

Here are some example probe points, defining the associated events.

begin, end, end: refers to the startup and normal shutdown of the session. In this case, the handler would run once during startup and twice during shutdown.
timer.jiffies(1000).randomize(200): refers to a periodic interrupt, every 1000 +/- 200 jiffies.
kernel.function("*init*"), kernel.function("*exit*"): refers to all kernel functions with "init" or "exit" in the name.
kernel.function("[EMAIL PROTECTED]/sched.c:240"): refers to any functions within the "kernel/sched.c" file that span line 240.
kernel.mark("getuid"): refers to an STAP_MARK(getuid, ...) macro call in the kernel.
module("usb*").function("*sync*").return: refers to the moment of return from all functions with "sync" in the name in any of the USB drivers.
kernel.statement(0xc0044852): refers to the first byte of the statement whose compiled instructions include the given address in the kernel.
kernel.statement("[EMAIL PROTECTED]/sched.c:2917"): refers to the statement of line 2917 within the "kernel/sched.c".
syscall.*.return: refers to the group of probe aliases with any name in the third position

Referenced By

stapex(5), staprun(8)

[linuxkernelnewbies] stapprobes(5): systemtap probe points - Linux man page

stapprobes(5) - Linux man page

Name

Description

Examples

See Also

Referenced By

Reply via email to