Tutorial: Using Project D-Light to Analyze Program Performance

Print-friendly Version

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

• Project D-Light System Requirements
• How to Provide Feedback to Sun
• D-Light Basic Workflow
• Instrumentation
• Targets
• Running an Experiment
• Manipulating the Display
• Examples of Use

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

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.

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,dtrace_kernel user

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

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

When the D-Light Tool is running, the basic workflow consists of these actions:

• 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, as shown in the following figure.

Figure 1. Displaying Instruments in the Sun Studio IDE Click here for a larger image.

When the instrument list is displayed, 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, as shown in the following figure.

Figure 2. Selecting the Target Application to Monitor Click here for a larger image.

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

To run an experiment, click the Record button.

The data that the individual instruments return is displayed 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.

The information that is returned by the instruments is displayed in the main D-Light Tool window. To zoom in on the data and fill the display window, click the Timeline Reset button, as shown in the following figure.

Figure 3. Using the Timeline Reset Button to Fill the Display Window Click here for a larger image.

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, as shown in the following figure.

Figure 4. Displaying Timelines Reported by Different Instruments Click here for a larger image.

To display the Dtracelet code that is associated with a specific instrument, click the instrument icon at the far left, as shown in the following figure.

Figure 5. Displaying Dtracelet Code Click here for a larger image.

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, as shown in the following figure.

Figure 6. Resetting the Timeline Click here for a larger image.

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, as shown in the following figure.

Figure 7. Changing the Color Maps on Timelines Click here for a larger image.

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.

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.

This example runs a simple experiment on the tar(1) application that is available on the Solaris OS, as shown in the following figure.

Figure 8. Running a Simple Example Experiment Click here for a larger image.

Specify the command-line arguments and options for the tar(1) application after clicking the Select Target button and choosing the Run Executable button, as shown in the following figure.

Figure 9. Specifying Command-Line Arguments and Options Click here for a larger image.

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.

Figure 10. Example Experiment Data Click here for a larger image.

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 the Timeline Reset button, as shown in the following figure.

Figure 11. Using the Timeline Reset Button to Fill the Display Window Click here for a larger image.

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 in front of the activity spike and continue dragging the cursor until the events you want to examine are outlined, as shown in the following figure.

Figure 12. Zooming to Examine an Activity Spike Click here for a larger image.

You can explore individual events by clicking the specific events or by clicking the Previous and Next event buttons that are located in the right-most event details panel, as shown in the following figure.

Figure 13. Exploring Events Using Previous and Next Buttons Click here for a larger image.

You can navigate between individual timelines by using the Up and Down buttons to correlate the data that is reported by different tools, as shown in the following figure.

Figure 14. Navigating Timelines Using Up and Down Buttons Click here for a larger image.

In this example, 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 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 is 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 the topmost panel and select the Reset Timeline option from the right-click pop-up menu (or press Control-Alt-R), and then dismiss the I/O Monitor instrument by clicking the red x in the top left corner of the instrument's miniature window, as shown in the following figure.

Figure 15. Removing an Instrument Click here for a larger image.

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, as shown in the following figure.

Figure 16. Using the Clock Profiler and Java Object Creation Monitor Instrumentst Click here for a larger image.

Specify how the Java2D demo executes by clicking the Select Target button and selecting the Run Java Application option, as shown in the following figure.

Figure 17. Selecting the Java Application to Run Click here for a larger image.

After you click the Record button, the Clock Profiler instrument generates multiple timelines. Each timeline corresponds to a separate execution thread. The tool tip 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 the black arrow at the right side of the miniature instrument window, as shown in the following figure.

Figure 18. Collapsing Timelines Click here for a larger image.

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

Figure 19. Adjusting the Height of a Timeline to Make All Stack Elements Visible Click here for a larger image.

The Java Object Creation Monitor instrument reports a high number of events, because 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 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, and then press Enter. The Colors Selection panel is shown in the following figure.

Figure 20. Selecting Colors to Clarify the Display Click here for a larger image.

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 is displayed in the IDE, as shown in the following figure.

Figure 21. Java Source Code Displayed in the IDE Click here for a larger image.