D-Light System Requirements

D-Light currently runs on the Solaris OS, at least version 10. To use D-Light with Java^TM applications, the system must have a DTrace enabled Java Runtime Environment, at least version 6, installed. The Solaris Express Developer Edition 11/08 OS, which is available free of charge from http://developers.sun.com/solaris/downloads/solexpdev/, is the recommended platform to run the tool. To check your Solaris version, type cat /etc/release at a shell prompt.

To run D-Light, your user account must have the dtrace_user, dtrace_proc, and dtrace_kernel privileges. Not all tools require all privileges. If your user account lacks a privilege that a tool requires, the tools that require that privilege are unavailable. To check your user privileges, type /bin/ppriv -v $$ | grep dtrace at a shell prompt. If your account doesn't have the required privileges, consult your system administrator. If you have superuser privileges, you can grant your user account the required privileges.

To Permanently Grant Required D-Light Privileges to a User Account

Make sure that the user account whose privileges you are about to modify is logged out of the system.
Become superuser.

Issue the following command:

$ usermod -K defaultpriv=basic,dtrace_user,dtrace_proc user

To Temporarily Grant Required D-Light Privileges to a User's Shell

Issue the following command to determine the PID of the shell's process:
```
$ echo $$
```
Become superuser.
In another shell, issue the following command:
```
$ ppriv -s I+dtrace_user,dtrace_proc,dtrace_kernel PID
```
All commands issued from the shell with a process ID of PID inherit the required privileges.

Feedback Directions

D-Light exists to gather user feedback. Please visit the Sun Studio Tools Forum at the Sun Developer Network site http://forum.java.sun.com/forum.jspa?forumID=852 to submit suggestions, praise, and criticism.

D-Light Basic Workflow

D-Light is a plug-in in the Sun Studio IDE. Start D-Light by clicking the D-Light button on the main SunStudio toolbar. SunStudio displays three panes when D-Light starts:

The main D-Light pane in the top right of the SunStudio window.
The D-Light Instruments pane in the top left of the SunStudio window.
The D-Light Event Details pane in the bottom left of the SunStudio window.

Once D-Light is running, the basic workflow consists of:

Choosing a target for the D-Light instruments
Choosing the instruments that D-Light monitors as the target runs
Analyzing the data that D-Light returns
Using the returned data to refine the experiment

Repeat the cycle above until the behavior of the application under analysis is clear.

Choosing Instruments

The D-Light plug-in provides several instruments that you can use to analyze your application's behavior. Choose an instrument from the D-Light Instruments panel at in the top left of the main SunStudio window. The D-Light tool displays the Instruments panel when you press the Alt-L keyboard shortcut or click the “Show D-Light Instruments Panel” button in the top left corner of the D-Light tool's main window.

This image shows D-Light's “Show D-Light Instruments Panel” button.

Drag and drop individual instruments to the vertical blue bar at the left edge of the main D-Light Tool window. You can also double-click on an instrument to select it.

Running D-Light on the SunStudio main project

From the D-Light drop-down button on the main SunStudio toolbar, choose 'D-Light Main Project' to analyze the code in SunStudio's main project.

Clicking the 'Run' button in the D-Light toolbar runs the application in SunStudio's main project and monitors the instruments that are in the main D-Light pane.

Running D-Light with Remote Development

When you develop your code on a local machine and run the application on a remote machine, you can run D-Light instrumentation on the remote machine by configuring D-Light for remote development.

Configuring a Project for Remote Development

Select 'Options' from the 'Tools' menu to display the Options dialog.
Select the 'C/C++' button in the Options dialog toolbar.
From the 'Build Tools' tab, click the 'Edit' button to display the 'Development Hosts Manager' dialog.
Click 'Add' to display the 'Add New Server' dialog.
Enter the remote host's name, user account login, and password.

Selecting a Remote Host as a Build Target

Before You Begin

Configure your project for remote development before starting this procedure.

Right-click on the project's name in SunStudio's 'Projects' pane and select 'Properties' to display the Project Properties dialog.
Choose 'Build' in the Categories tree of the Project Properties dialog.
Click on the drop-down selector for 'Development Host' and select the remote host.

Running D-Light on an ELF Executable

Choose 'D-Light Executable' to browse for an ELF executable. The D-Light tool displays the 'Select Executable Target' dialog.

This image shows the 'Select Executable Target' dialog, with three fields: 'Executable', 'Arguments', and 'Working Directory'. The 'Executable' and 'Working Directory' fields have 'Browse' buttons next to them, and the dialog has an 'OK' button and a 'Cancel' button.

Type the path to the executable in the 'Executable' field, or click the 'Browse' button to browse for an executable. Type any arguments to pass to the executable in the 'Arguments' field. You can specify a working directory in the 'Working Directory' field or click on the 'Browse' button to browse for a directory. Clicking the 'OK' button accepts the contents of the fields and closes the dialog. Clicking the 'Run' button in the D-Light toolbar runs the application that you specified in the 'Executable' field and monitors the instruments that are in the main D-Light pane.

Running D-Light on a Java Executable

Choose 'D-Light Java Executable' to browse for a JAR file. The D-Light tool displays the 'Select Java Application' dialog.

This image shows the 'Select Java Application' dialog, with seven fields: 'JVM Path', 'JVM Options', 'JAR File', 'Main Class', 'Arguments', 'Class Path', and 'Working Directory'. The 'JVM Path', 'JAR File', and 'Working Directory' fields have 'Browse' buttons next to them, and the dialog has an 'OK' button and a 'Cancel' button.

Make sure the 'JVM Path' field contains the correct path to your JVM installation, or click on the 'Browse' button to browse for a directory. Type any options you want to pass to the JVM in the 'JVM Options' field. Type the path to the JAR file in the 'JAR File' field, or click on the 'Browse' button to browse for a JAR file. You can specify a working directory in the 'Working Directory' field or click on the 'Browse' button to browse for a directory. You can choose the main class from the 'Main Class' drop-down or type in a main class. Clicking the 'OK' button runs the Java executable that you specified in the 'JAR File' field and monitors the instruments you selected.

Note - To use the JDK's DTrace probes, pass -XX:+ExtendedDTraceProbes as an option to the JVM as an option in the 'JVM Options' field.

Note - Monitoring attached processes is not currently supported. The 'D-Light Attached Process' option is unavailable.

During an Experimental Run

When you select a target for your instrumentation, the target application runs. The data that the individual instruments return displays in real time. Click the Stop button to end the experiment or wait for the application to finish. To examine and interpret the application's behavior, navigate the individual timelines examining events and finding correlations between events that happen simultaneously.

Display Manipulation Tasks

The information that the instruments return displays in the main D-Light Tool window. To zoom in on the data and fill the display window, click on the Fit to Screen button or use the Alt-F keyboard shortcut.

The icon for the 'Fit to Screen' button is a magnifying glass with an equals sign inside it.

To zoom in on a specific region of the timeline, click and drag in the timeline window to outline the desired region.

Click the up and down buttons on the D-Light pane's toolbar to change the display to the timelines reported by different instruments. You can also use the Alt-U (up) and Alt-W (down) keyboard shortcuts.

To display the D-script code that is associated with a specific instrument, right-click the instrument icon and select 'D-Script' from the drop-down menu.

To reset the timeline, click the 'Reset Collected Data' button on the D-Light pane's toolbar, or use the Alt-R keyboard shortcut.

The 'Reset Collected Data' button has an image of a broom.

Note - You cannot make changes to the instruments in the main D-Light pane while the pane is displaying existing data. You must clear the collected data before changing the instrumentation.

To move an instrument's timeline up or down in the list, drag and drop the instrument's icon to a different location on the instrument panel.

To change the color masks that are associated with the events reported on an instrument's timeline, click the 'Show Color Masks Dialog' button on the D-Light pane's toolbar, or use the Alt-C keyboard shortcut.

The 'Show Color Masks Dialog' button has an image of three colored circles that overlap in the center.

To display the source code that is associated with a particular monitored event, double-click any element of the stack in the instrument's timeline. For C and C++ source code, you must compile the application with the debug info option -g enabled.