11.6.1 Probe Clauses

The software described in this documentation is either in Extended Support or Sustaining Support. See https://www.oracle.com/us/support/library/enterprise-linux-support-policies-069172.pdf for more information.
Oracle recommends that you upgrade the software described by this documentation as soon as possible.

11.6.1 Probe Clauses

D programs consist of a set of one or more probe clauses. Each probe clause takes the general form shown here:

probe_description_1 [, probe_description_2]...
[/ predicate_statement /]
{
  [action_statement;]
  .
  .
  .
}

Every probe clause begins with a list of one or more probe descriptions in this form:

provider:module:function:probe_name

where the fields are as follows:

provider: The name of the DTrace provider that is publishing this probe. For kernel probes, the provider name typically corresponds to the name of the DTrace kernel module that performs the instrumentation to enable the probe, for example, proc. When tracing a DTrace-enabled, user-space application or library, this field takes the form namePID, where name is the name of the provider as defined in the provider definition file that was used to build the application or library and PID is the process ID of the running executable.
module: The name of the kernel module, library, or user-space program in which the probe is located, if any, for example, vmlinux. This module is not the same as the kernel module that implements a provider.
function: The name of the function in which the probe is located, for example, do_fork.
probe_name: The name of the probe usually describes its location within a function, for example, create, entry, or return.

The compiler interprets the fields from right to left. For example, the probe description settimeofday:entry would match a probe with function settimeofday and name entry regardless of the value of the probe's provider and module fields. You can regard a probe description as a pattern that matches one or more probes based on their names. You can omit the leading colons before a probe name if the probe that you want to use has a unique name. If several providers publish probes with the same name, use the available fields to obtain the correct probe. If you do not specify a provider, you might obtain unexpected results if multiple probes have the same name. Specifying a provider but leaving the module, function, and probe name fields blank, matches all probes in a provider. For example, syscall::: matches every probe published by the syscall provider.

The optional predicate statement uses criteria such as process ID, command name, or timestamp to determine whether the associated actions should take place. If you omit the predicate, any associated actions always run if the probe is triggered.

You can use the ?, *, and [] shell wildcards with probe clauses. For example, syscall::[gs]et*: matches all syscall probes for function names that begin with get or set. If necessary, use the \ character to escape wildcard characters that form part of a name.

You can enable the same actions for more than one probe description. For example, the following D program uses the trace() function to record a timestamp each time that any process invokes a system call containing the string mem or soc:

syscall::*mem*:entry, syscall::*soc*:entry
{
        trace(timestamp);
}

By default, the trace() function writes the result to the principal buffer, which is accessible by other probe clauses within a D program, and whose contents dtrace displays when the program exits.