[ новости /+++ | форум | теги | ]

NAME

stapprobes - systemtap probe points





 

DESCRIPTION

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)

NEVER

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)

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)

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

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)

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("*@kernel/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("*@kernel/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

SEE ALSO

Index

NAME

DESCRIPTION

BEGIN/END

NEVER

TIMERS

DWARF

MARKERS

PERFORMANCE MONITORING HARDWARE

EXAMPLES

SEE ALSO

Партнёры:

Хостинг: