2.1.2 Probe Descriptions

Every program clause begins with a list of one or more probe descriptions, each taking the following usual form:

provider:module:function:name

If one or more fields of the probe description are omitted, the specified fields are interpreted from right to left by the D compiler. For example, the probe description foo:bar would match a probe with the function foo and name bar, regardless of the value of the probe's provider and module fields. Therefore, a probe description is really more accurately viewed as a pattern that can be used to match one or more probes based on their names.

You should write your D probe descriptions specifying all four field delimiters so that you can specify the desired provider on the left-hand side. If you don't specify the provider, you might obtain unexpected results if multiple providers publish probes with the same name. Similarly, subsequent versions of DTrace might include new providers with probes that unintentionally match your partially specified probe descriptions. You can specify a provider but match any of its probes by leaving any of the module, function, and name fields blank. For example, the description syscall::: can be used to match every probe that is published by the DTrace syscall provider.

Probe descriptions also support a pattern-matching syntax similar to the shell globbing pattern matching syntax that is described in the sh(1) manual page. Before matching a probe to a description, DTrace scans each description field for the characters *, ?, and [. If one of these characters appears in a probe description field and is not preceded by a \, the field is regarded as a pattern. The description pattern must match the entire corresponding field of a given probe. To successfully match and enable a probe, the complete probe description must match on every field. A probe description field that is not a pattern must exactly match the corresponding field of the probe. Note that a description field that is empty matches any probe.

The special characters in the following table are recognized in probe name patterns.

Table 2.1 Probe Name Pattern Matching Characters

Symbol

Description

*

Matches any string, including the null string.

?

Matches any single character.

[...]

Matches any one of the enclosed characters. A pair of characters separated by - matches any character between the pair, inclusive. If the first character after the [ is !, any character not enclosed in the set is matched.

\

Interpret the next character as itself, without any special meaning.


Pattern match characters can be used in any or all of the four fields of your probe descriptions. You can also use patterns to list matching probes by them on the command line by using the dtrace -l command. For example, the dtrace -l -f kmem_* command lists all of the DTrace probes in functions with names that begin with the prefix kmem_.

If you want to specify the same predicate and actions for more than one probe description, or description pattern, you can place the descriptions in a comma-separated list. For example, the following D program would trace a timestamp each time probes associated with entry to system calls containing the strings “read” or “write” fire:

syscall::*read*:entry, syscall::*write*:entry
{
  trace(timestamp);
}

A probe description can also specify a probe by using its integer probe ID, for example, the following clause could be used to enable probe ID 12345, as reported by dtrace -l -i 12345:

12345
{
  trace(timestamp);
}
Note

You should always write your D programs using human-readable probe descriptions. Integer probe IDs are not guaranteed to remain consistent as DTrace provider kernel modules are loaded and unloaded or following a reboot.