Table of Contents
Complex sets of DTrace probes can become difficult to manage on the
command line. The dtrace command supports scripts. You
can specify a script by passing the
s option, along with
the script's file name, to the dtrace command. You can
also create executable DTrace interpreter files. A DTrace interpreter file
always begins with the line #!/usr/sbin/dtrace -s.
This example script, named syscall.d, traces the
executable name every time the executable enters each system call:
syscall:::entry
{
trace(execname);
}
Note that the filename ends with a .d suffix. This is the conventional ending for D scripts. You can run this script off the DTrace command line with the following command:
# dtrace -s syscall.d dtrace: description 'syscall ' matched 226 probes CPU ID FUNCTION:NAME 0 312 pollsys:entry java 0 98 ioctl:entry dtrace 0 98 ioctl:entry dtrace 0 234 sysconfig:entry dtrace 0 234 sysconfig:entry dtrace 0 168 sigaction:entry dtrace 0 168 sigaction:entry dtrace 0 98 ioctl:entry dtrace ^C
You can run the script by entering the filename at the command line
by following two steps. First, verify that the first line of the file invokes
the interpreter. The interpreter invocation line is #!/usr/sbin/dtrace
-s. Then set the execute permission for the file.
Example 3.1. Running a D Script from the Command Line
# cat syscall.d #!/usr/sbin/dtrace -s syscall:::entry { trace(execname); } # chmod +x syscall.d # ls -l syscall.d -rwxr-xr-x 1 root other 62 May 12 11:30 syscall.d # ./syscall.d dtrace: script './syscall.d' matched 226 probes CPU ID FUNCTION:NAME 0 98 ioctl:entry dtrace 0 98 ioctl:entry dtrace 0 312 pollsys:entry java 0 312 pollsys:entry java 0 312 pollsys:entry java 0 98 ioctl:entry dtrace 0 98 ioctl:entry dtrace 0 234 sysconfig:entry dtrace 0 234 sysconfig:entry dtrace ^C
The D language supports literal strings. DTrace represents strings
as an array of characters terminated by a null byte. The visible part of the
string varies in length depending on the location of the null byte. DTrace
stores each string in a fixed-size array to ensure that each probe traces
a consistent amount of data. Strings cannot exceed the length of the predefined
string limit. The limit can be modified in your D program or on the dtrace command line by tuning the strsize option. Refer
to Chapter 16, Options and Tunables, in Solaris
Dynamic Tracing Guide
for more information on tunable
DTrace options. The default string limit is 256 bytes.
The D language provides an explicit string type
rather than using the type char * to refer to strings.
See Chapter 6, Strings, in Solaris Dynamic
Tracing Guide
for more information about D literal strings.
Example 3.2. Using D Literal Strings With The trace
Function
# cat string.d
#!/usr/sbin/dtrace -s
fbt::bdev_strategy:entry
{
trace(execname);
trace(" is initiating a disk I/O\n");
}
The \n symbol at the end of the literal string produces
a new line. To run this script, enter the following command:
# dtrace -s string.d dtrace: script 'string.d' matched 1 probes CPU ID FUNCTION:NAME 0 9215 bdev_strategy:entry bash is initiating a disk I/O 0 9215 bdev_strategy:entry vi is initiating a disk I/O 0 9215 bdev_strategy:entry vi is initiating a disk I/O 0 9215 bdev_strategy:entry sched is initiating a disk I/O ^C
The
q option of the dtrace command
only records the actions that are explicitly stated in the script or command
line invocation. This option suppresses the default output that the dtrace command normally produces.
# dtrace -q -s string.d ls is initiating a disk I/O cat is initiating a disk I/O fsflush is initiating a disk I/O vi is initiating a disk I/O ^C
You can use the dtrace command to create executable
interpreter files. The file must have execute permission. The initial line
of the file must be #!/usr/sbin/dtrace -s. You can specify
other options to the dtrace command on this line. You must
specify the options with only one dash (-). List the s option last, as in the following example.
#!/usr/sbin/dtrace -qvs
You can specify options for the dtrace command by
using #pragma lines in the D script, as in the following
D fragment:
# cat -n mem2.d
1 #!/usr/sbin/dtrace -s
2
3 #pragma D option quiet
4 #pragma D option verbose
5
6 vminfo:::
...
The following table lists the option names that you can use in #pragma lines.
Table 3.1. DTrace Consumer Options
|
Option Name |
Value |
dtrace Alias |
Description |
|---|---|---|---|
|
|
|
Rate of aggregation reading | |
|
|
|
Aggregation buffer size | |
|
|
|
Buffer resizing policy | |
|
|
|
|
Principal buffer size |
|
|
|
Cleaning rate | |
|
|
|
|
CPU on which to enable tracing |
|
|
— |
Allow references to unspecified macro arguments | |
|
|
— |
|
Allow destructive actions |
|
|
|
Dynamic variable space size | |
|
|
— |
|
Indent function entry and prefix with |
|
|
— |
|
Claim anonymous state |
|
|
|
Number of default stack frames | |
|
|
|
Default string space size for | |
|
|
|
Number of speculations | |
|
|
— |
|
Output only explicitly traced data |
|
|
|
Speculation buffer size | |
|
|
|
String size | |
|
|
|
Number of stack frames | |
|
|
|
Number of whitespace characters to use when indenting | |
|
|
|
Rate of status checking | |
|
|
|
Rate of buffer switching | |
|
|
|
Number of user stack frames |
A D script can refer to a set of built in macro variables. These macro variables are defined by the D compiler.
$[0-9]+
Macro arguments
$egid
Effective group-ID
$euid
Effective user-ID
$gid
Real group-ID
$pid
Process ID
$pgid
Process group ID
$ppid
Parent process ID
$projid
Project ID
$sid
Session ID
$target
Target process ID
$taskid
Task ID
$uid
Real user-ID
Example 3.3. PID Argument Example
This example passes the PID of a running vi process
to the syscalls2.d D script. The D script terminates
when the vi command exits.
#cat -n syscalls2.d1 #!/usr/sbin/dtrace -qs 2 3 syscall:::entry 4 /pid == $1/ 5 { 6 @[probefunc] = count(); 7 } 8 syscall::rexit:entry 9 { 10 exit(0); 11 } #pgrep vi2208 #./syscalls2.d 2208rexit 1 setpgrp 1 creat 1 getpid 1 open 1 lstat64 1 stat64 1 fdsync 1 unlink 1 close 1 alarm 1 lseek 1 sigaction 1 ioctl 1 read 1 write 1