Project D-Light Tutorial

D-Light Tutorial

Project D-Light is a plug-in for Sun Studio 12. The plug-in offers a variety of instrumentation that takes advantage of the DTrace debugging and performance analysis functionality in the Solaris Operating System.

Project D-Light System Requirements

Project D-Light currently only runs on the Solaris 10 OS and requires a DTrace enabled Java Runtime Environment, at least version 6. The Solaris Express Developer Edition 05/07 OS, which is available free of charge from, is the recommended platform to run the tool. To check your Solaris version, type cat /etc/release at a shell prompt.

The Java Runtime Environment (JRE) version 5 is the recommended version for running the Sun Studio IDE. To control the JRE version, specify the --jdkhome option at the command line when you start Sun Studio:

$ sunstudio --jdkhome /usr/jdk/jdk1.5.0_11

To run Project D-Light, your user account must have the dtrace_user, dtrace_proc, and dtrace_kernel privileges. To check your user privileges, type /bin/ppriv $$ | 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 Grant Required D-Light Privileges to a User Account

  1. Make sure that the user account whose privileges you are about to modify is logged out of the system.
  2. Become superuser.
  3. Issue the following command:
    $ $ usermod -K defaultpriv=basic,dtrace_user,dtrace_proc user

Feedback Directions

Project D-Light exists to gather user feedback. Please visit the Sun Studio Tools Forum at the Sun Developer Network site to submit suggestions, praise, and criticism.

D-Light Basic Workflow

Project D-Light is a plug-in in the Sun Studio IDE. You access the plug-in by choosing the D-Light Tool option from the Tools menu.

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

  • Setting up an experiment

  • Analyzing the data that Project 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.


The D-Light plug-in provides several instruments that you can use to analyze your application's behavior. You choose an instrument from the Instruments drop-down menu.

Once the instrument list displays, you can drag and drop individual instruments to the vertical panel on the left. You can also select an instrument by double-clicking it.


When you've selected the instrumentation, select the application you want to monitor by clicking the Select Target button:

After selecting the instrumentation and the application target, the experiment is ready to run.

Running an Experiment

To run an experiment, click the Record button.

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 is returned by the instruments displays in the main D-Light Tool window. To zoom in on the data and fill the display window, click on the Timeline Reset button.

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

To enable comparisons between the events that are reported by different instruments, click the up and down buttons in the group of arrows on the right to change the display to the timelines reported by different instruments.

To display the Dtracelet code that is associated with a specific instrument, clicking the instrument icon at the far left displays the DTracelet code that is associated with that instrument.

To reset the timeline, click mouse button 3 on the topmost panel and choose the Reset Timeline option from the pop-up menu, or press Control-Alt-R.

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 maps that are associated with the events reported on an instrument's timeline, click mouse button 3 in the timeline and choose the Colors option from the pop-up menu, or click the Colors button in the top panel.

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.

Examples of Use

This section provides two case studies of D-Light use, one for a C/C++ application and one for a Java application. These examples illustrate that D-Light can profile an application and its interaction with the system without requiring recompilation or access to the source code.

Example 1 Exploring a C/C++ Application

This example runs a simple experiment on the tar(1) application that is available on the Solaris operating system.

Specify the command-line arguments and options for the tar(1) application after clicking the Select Target button and choosing the Run Executable button.

After clicking the Record button and waiting for the tar(1) application to finish running, D-Light displays the following representation of the data that was collected during the experiment:

On most systems, there will be significantly more screen real estate than data. To zoom to the level that fits all the available data to the screen, click on the Timeline Reset button:

D-Light now displays two timeline panels from two separate instruments. Each timeline represents individual events as colored bars. Each bar from the Clock Profiler instrument in the topmost timeline panel represents a stack of the functions that execute as part of the tar(1) application. Each function is associated with a color. To zoom in around a spike of activity that appears to have some corresponding I/O data in the bottom timeline, left-click before the activity spike and continue dragging the cursor until the events you want to examine are outlined.

You can explore individual events by clicking on the specific events or by clicking on the Previous and Next event buttons that are located in the right-most event details panel:

You can navigate between individual timelines by using the Up and Down buttons to correlate the data that is reported by different tools.

The tar(1) application executed a call to the putfile() function. The putfile() function caused a system call to the write(2)() utility, transferring 5120 bytes of data. Clicking on the Next Event button while keeping the focus on the lower timeline reveals the I/O patterns of the tar(1) application and correlates it with the system's behavior and application-level control flow. Throughout this example, D-Light has been able to profile the application and its interaction with the system without requiring recompilation or access to the source code.

To reset the timelines for the next example, right-click on the topmost panel and select the Reset Timeline option from the right-click pop-up menu or press Control-Alt-R, then dismiss the I/O Monitor instrument by clicking the red x in the top left corner of the instrument's miniature window.

Example 2 Exploring a Java Application

This example runs a simple experiment on a Java2D application that is installed along with the JDK. This example uses the Clock Profiler and Java Object Creation Monitor instruments.

Specify how the Java2D demo executes by clicking on the Select Target button and selecting the Run Java Application option.

After pressing the Record button, the Clock Profiler instrument generates multiple timelines. Each timeline corresponds to a separate execution thread. The tooltip that appears when you hover the cursor over the Clock Profiler icons contains information on the thread to which that particular timeline corresponds. To collapse the timelines you don't want to examine right now, click on the black arrow at the right side of the miniature instrument window.

This example focuses on the Clock Profiler timeline that corresponds to thread #2 and the Java Object Creation Monitor timeline. Since Java stacks are deep, we can adjust the height of the Clock Profiler timeline by dragging the divider downwards to make all the stack elements visible.

The Java Object Creation Monitor instrument reports a high number of events, since each time the system creates an object it generates an event. Each individual object is associated with a color. To cut through the visual clutter, change the color mapping that is associated with the events. To see each instance of the creation of an array of char variables, bring up the Colors panel by right-clicking in the Java Object Creation Monitor's timeline and selecting the Colors option. Select a pale color from the Swatches panel and click on the Set For All button. Select a dark color from the Swatches panel and enter [C (for char array creation events) in the Set For text field, make sure the drop-down is set to Exactly, then press the Enter key.

This color mapping makes the specific objects under observation visually distinct. To see the method that created a particular array, double-click the top element of the stack that is displayed in the right-most panel. The Java source code displays in the IDE.


A flash demo of D-Light in action would be excellent !!

Posted by Matt Keenan on July 19, 2007 at 05:33 AM PDT #

Post a Comment:
Comments are closed for this entry.

Application development on Solaris OS


« December 2016