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.
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:
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:
Alternatively, intervals may be specified in units of time.
There are two probe point variants similar to the jiffies timer:
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.
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
variant places a probe near the beginning of the named function, so that
parameters are available as context variables. The
variant places a probe at the moment of return from the named function, so
the return value is available as the "$return" context variable.
filters the results to include only instances of inlined functions.
modifier selects the opposite subset. Inline functions do not have an
identifiable return point, so
is not supported on
variant places a probe at the exact spot, exposing those local variables
that are visible there.
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.
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.
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
The next part of the names the event being counted
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:
Here are some example probe points, defining the associated events.