12.2 Installing and Configuring DTrace

12.2.1 Changing the Mode of the DTrace Helper Device
12.2.2 Loading DTrace Kernel Modules
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 6 Update 4 or later.

To install and configure DTrace, perform the following steps:

  1. On ULN, subscribe your system 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)

    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 12.2.1, “Changing the Mode of the DTrace Helper Device”.

You can find files that contain the latest information about the implementation of DTrace in /usr/share/doc/dtrace-DTrace_version.

12.2.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.

12.2.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, and the dtrace module automatically loads the ctf module.

To list the probes that a specific provider publishes, use the following command:

# dtrace -l -P provider

To verify that a probe is available:

# dtrace -l -n probe_name

To display the probes that are available for a specific module:

# dtrace -l -m module_name

For example, display the probes that are provided by the libphp5.so and mysqld modules for DTrace-enabled PHP and MySQL:

# dtrace -l -m libphp5.so -m mysqld
   ID   PROVIDER        MODULE                          FUNCTION NAME
    4    php3566    libphp5.so               dtrace_compile_file compile-file-entry
    5    php3566    libphp5.so               dtrace_compile_file compile-file-return
    6    php3566    libphp5.so                        zend_error error
    7    php3566    libphp5.so  ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
    8    php3566    libphp5.so     zend_throw_exception_internal exception-thrown
    9    php3566    libphp5.so                 dtrace_execute_ex execute-entry
   10    php3566    libphp5.so           dtrace_execute_internal execute-entry
   11    php3566    libphp5.so                 dtrace_execute_ex execute-return
   12    php3566    libphp5.so           dtrace_execute_internal execute-return
   13    php3566    libphp5.so                 dtrace_execute_ex function-entry
   14    php3566    libphp5.so                 dtrace_execute_ex function-return
   15    php3566    libphp5.so              php_request_shutdown request-shutdown
   16    php3566    libphp5.so               php_request_startup request-startup
...
  121  mysql3684        mysqld _Z16dispatch_command19enum_server_commandP3THDPcj 
                                                                 command-done
  122  mysql3684        mysqld _Z16dispatch_command19enum_server_commandP3THDPcj
                                                                 command-start
  123  mysql3684        mysqld        _Z16close_connectionP3THDj connection-done
  124  mysql3684        mysqld   _Z22thd_prepare_connectionP3THD connection-start
  125  mysql3684        mysqld    _Z21mysql_execute_commandP3THD delete-done
  126  mysql3684        mysqld    _ZN7handler13ha_delete_rowEPKh delete-row-done
  127  mysql3684        mysqld    _ZN7handler13ha_delete_rowEPKh delete-row-start
  128  mysql3684        mysqld    _Z21mysql_execute_commandP3THD delete-start
  129  mysql3684        mysqld _Z8filesortP3THDP5TABLEP8FilesortbPyS5_ 
                                                                 filesort-done
  130  mysql3684        mysqld _Z8filesortP3THDP5TABLEP8FilesortbPyS5_
                                                                 filesort-start
...
Note

For DTrace-enabled, user-space programs, this command requires the fasttrap module to have been loaded before the program was started, and it does not return any probes if no instance of the program is running. dtrace appends the PID of the process to the DTrace provider name that was defined for the program when it was built.