1.4 Preparation: Installing and Configuring DTrace

Note

The DTrace dtrace-utils package is available from ULN. Your system must be registered with ULN and be installed with or be updated to Oracle Linux Release 6 Update 4 or later or Oracle Linux 7.

To install and configure DTrace, perform the following steps:

  1. On ULN, subscribe your system to the appropriate channels.

    For Oracle Linux 6 Update 4 or later, subscribe to the following channels:

    • Oracle Linux 6 Latest (x86_64) (ol6_x86_64_latest)

    • Unbreakable Enterprise Kernel Release 3 for Oracle Linux 6 (x86_64) - Latest (ol6_x86_64_UEKR3_latest)

    • Oracle Linux 6 Dtrace Userspace Tools (x86_64) - Latest (ol6_x86_64_Dtrace_userspace_latest)

    For Oracle Linux 7, subscribe to the following channels:

    • Oracle Linux 7 Latest (x86_64) (ol7_x86_64_latest)

    • Unbreakable Enterprise Kernel Release 3 for Oracle Linux 7 (x86_64) - Latest (ol7_x86_64_UEKR3)

    • Oracle Linux 7 Dtrace Userspace Tools (x86_64) - Latest (ol7_x86_64_Dtrace_userspace)

    Note

    Make sure that your system is not subscribed to the following channels:

    • Latest Unbreakable Enterprise Kernel for Oracle Linux 6 (x86_64) (ol6_x86_64_UEK_latest)

    • Dtrace for Oracle Linux 6 (x86_64) - Latest (ol6_x86_64_Dtrace_latest)

    • Dtrace for Oracle Linux 6 (x86_64) - Beta release (ol6_x86_64_Dtrace_BETA)

    • Unbreakable Enterprise Kernel Release 3 (3.8 based) for Oracle Linux 6 (x86_64) - Beta release (ol6_x86_64_UEK_BETA)

    These channels are applicable to UEK R2, DTrace for UEK R2, the beta release of DTrace for UEK R2, and the beta release of UEK R3.

  2. If your system is not already running the latest version of the Unbreakable Enterprise Kernel Release 3 (UEK R3):

    1. Use yum to update your system to use UEK R3:

      # yum update
    2. Reboot the system, selecting the Oracle Linux Server (3.8.13) kernel in the GRUB menu if it is not the default kernel.

  3. Use yum to install the DTrace utilities package:

    # yum install dtrace-utils

If you subsequently use yum update to install a new kernel, yum does not automatically install the matching dtrace-modules package that the kernel requires. If the appropriate dtrace-modules package for the running kernel is not present on the system, the dtrace command downloads and installs the package from ULN. To invoke this action without performing a trace, use a command such as the following:

# dtrace -l

Alternatively, run the following command to install the DTrace module that is appropriate to the running kernel:

# yum install dtrace-modules-`uname -r`

If you want to implement a libdtrace consumer or develop a DTrace provider, use yum to install the dtrace-utils-devel or dtrace-modules-provider-headers package respectively.

To be able to trace user-space processes that are run by users other than root, change the mode of the DTrace helper device as described in Section 1.4.1, “Changing the Mode of the DTrace Helper Device”.

1.4.1 Changing the Mode of the DTrace Helper Device

The DTrace helper device (/dev/dtrace/helper) allows a user-space application that contains DTrace probes to send probe provider information to DTrace.

To trace user-space processes that are run by users other than root, you must change the mode of the DTrace helper device to allow the user to record tracing information, for example:

# chmod 666 /dev/dtrace/helper

Alternatively, if the acl package is installed on your system, you can use an ACL rule to limit access to a specific user, for example:

# setfacl -m u:guest:rw /dev/dtrace/helper
Note

You must change the mode on the device before the user runs the program.

You can create a udev rules file such as /etc/udev/rules.d/10-dtrace.rules to change the permissions on the device file when the system starts.

To change the mode of the device file, the udev rules file should contain the following line:

kernel=="dtrace/helper", MODE="0666"

To change the ACL settings for the device file, use a line such as the following in the udev rules file:

kernel=="dtrace/helper", RUN="/usr/bin/setfacl -m u:guest:rw /dev/dtrace/helper"

To apply the udev rule without needing to restart the system, run the start_udev command.

1.4.2 Loading DTrace Kernel Modules

Use the modprobe command to load the modules that support the DTrace probes that you want to use. For example, if you wanted to use the probes that the proc provider publishes, you would load the sdt module.

# modprobe sdt
Note

The fasttrap, profile, sdt, and systrace modules automatically load the dtrace module.

To display the probes that are provided by a provider such as proc, use the following form of the dtrace command:

# dtrace -l -P proc
   ID   PROVIDER            MODULE                          FUNCTION NAME
 3466       proc           vmlinux                     schedule_tail start
 3467       proc           vmlinux                     schedule_tail lwp-start
 3469       proc           vmlinux             get_signal_to_deliver signal-handle
 3474       proc           vmlinux                   do_sigtimedwait signal-clear
 3475       proc           vmlinux                           do_fork lwp-create
 3476       proc           vmlinux                           do_fork create
 3477       proc           vmlinux                           do_exit lwp-exit
 3478       proc           vmlinux                           do_exit exit
 3479       proc           vmlinux                  do_execve_common exec-failure
 3480       proc           vmlinux                  do_execve_common exec
 3481       proc           vmlinux                  do_execve_common exec-success
 3485       proc           vmlinux                     __send_signal signal-send
 3486       proc           vmlinux                     __send_signal signal-discard

The output shows the numeric identifier of the probe, the name of the probe provider, the name of the probe module, the name of the function that contains the probe, and the name of the probe itself.

The full name of a probe is PROVIDER:MODULE:FUNCTION:NAME, for example, proc:vmlinux:do_fork:create. If there is no ambiguity with other probes for the same provider, you can usually omit the MODULE and even the FUNCTION elements when specifying a probe. For example, you can refer to proc:vmlinux:do_fork:create as proc::do_fork:create or proc:::create. If several probes match your specified probe in a D program, the associated actions are performed for each probe.

These probes allow you to monitor how the system creates processes, executes programs, and handles signals.