Probe point specification

Each probe point tuple identifies a code location whose execution or an event whose occurrence must trigger the probe actions. Multiple probe points can be associated with the same set of probe actions and the predicate, if any, by providing a comma-separated list of probe tuples at the top of the Vue clause.

The following are some of the probe types that are supported:

• User function entry probes (or uft probes)
• System call entry or exit probes (or syscall probes)
• Probes that fire at specific time intervals (or interval probes)

For a complete list of probe types that are supported, refer the probe manager section.

The probe point tuple is an ordered list of fields that are separated by colons that uniquely identify a probe point. It has the following general format, although the location field is usually present only if the probe point is a probe location.

@@ <probetype>:
<one or more probetype-specific fields separated by colons>:<location>

The probe manager defines the acceptable values for the probe-type specific fields in the probe point tuple and the length of the probe tuple. However, the following general rules are followed by all probe managers when defining probe point tuples:

• Each probe point tuple is at least a 3-tuple, that is, it has a minimum of 3 fields.
• The first field always identifies the probe type and thus its probe manager.
• For probe managers that support process-specific tracing, the second field must be a process ID.
• For probe managers that support function entry or exit probes, the location field (the last field) must use the entry or exit keyword.
• Fields are separated by the colon (:) symbol.
• An asterisk or the "*" symbol for a field in the probe point tuple indicates that it matches any possible value for that field. For example, the syscall probe manager allows for system calls of a specific process or for all processes to be probed. In the first case, the second field must be the process ID of the process to be probed. In the latter case, when all processes are to be probed, the second field must be the "*" symbol. A second use of the asterisk symbol for a field is to allow for finer-grained probes in the future while maintaining binary compatibility with existing scripts. For example, the uft probe manager currently requires the third field to be an asterisk. In the future, it can support a module name as the third field to limit probes to only functions defined in that module.
• Maximum length of the probe specification is 1023 characters.

For example:

@@uft:34568:*:foo:entry

Probe at entry into any function called foo in process with ID = 34568. The asterisk in the third field indicates that the foo function is to be probed if it exists in any module of the process.

@@syscall:*:read:exit

Probe at exit of the read system call. The asterisk indicates that the read system call for all processes are to be probed.

@@interval:*:clock:500

Probe to fire every 500 milliseconds (wall clock time). The asterisk is a placeholder for supporting finer probe points in the future.

The process ID for a process is often not known at the time the Vue script is written. Vue provides a simple method to avoid having to hard-code a process ID in the second field of the probe specification or anywhere in a Vue script (for example, in the predicate section).

A single Vue script can contain probe points from multiple processes in user space and in the kernel. Any trace output generated is always displayed in time order.

In addition to regular probe points defined by probe managers, Vue supports two special probe points. Each Vue script can contain a @@BEGIN probe point to indicate any action that needs to be issued before enabling any probes and an @@END probe point to indicate any action to be issued after the tracing has been terminated.

Action block

The action block identifies the trace actions to be performed when the associated probe point is triggered. Supported actions are not restricted to capturing and formatting of trace data but the full power of the Vue language can be employed.

An action block in Vue is similar to a procedure in procedural languages. It consists of a sequence of statements that are issued in order. The flow of execution is essentially sequential. The only exceptions are that conditional execution is possible using the "if-else" statement and control can be returned from the action block using the "return" statement. Vue also supports an exit function that terminates the entire script and ends the tracing session. There are no constructs for looping in Vue and C language statements, so "for", "do", "goto", and so on, are not supported.

Unlike procedures in procedural languages, an action block in Vue does not have an output or return value. It also does not have inherent support for a set of input parameters. On the other hand, the context data at the point where a probe is entered can be accessed within the action block. For example, the parameters passed to a function can be referenced within the action block of a Vue clause if the probe point is at the function's entry point.

Predicates

You must use predicates when execution of clauses at probe points must be performed conditionally. The predicate section is identified by the presence of the when keyword immediately after the probe specification section. The predicate itself consists of regular C-style conditional expressions with the enclosing parentheses.

  	when ( <condition> )

when ( __pid == 1678 )