// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= NetBeans DTrace GUI Plug-in
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: NetBeans DTrace GUI Plug-in - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, NetBeans DTrace GUI Plug-in

By Nasser Nouri, Sun Microsystems, July, 2008

This article describes how to download, install, and run the NetBeans^TM^ Dynamic Tracing (DTrace) GUI Plugin. The NetBeans DTrace GUI Plugin is a graphical user interface (GUI) for Solaris^TM^ Dynamic Tracing (DTrace), and can be installed into the Sun^TM^ Studio IDE, NetBeans^TM^ IDE 6.0, NetBeans IDE 6.1, and NetBeans IDE 6.5.

You can run D scripts from the GUI, even those that are embedded in shell scripts. In fact, the DTrace GUI Plugin runs all of the D scripts that are packaged in the link:http://www.opensolaris.org/os/community/dtrace/dtracetoolkit/[+DTraceToolkit+]. The DTraceToolkit is a collection of useful documented scripts developed by the OpenSolaris DTrace community.

You can visualize the output of DTrace using link:http://opensolaris.org/os/project/dtrace-chime/[+Chime+]. Chime is a graphical tool for visualizing link:http://www.opensolaris.org/os/community/dtrace/[+DTrace+] aggregations. In particular, its ability to display data over time adds a missing dimension to system observability. Chime is fully integrated with the NetBeans DTrace GUI Plugin.

An important feature of Chime is the ability to link:http://opensolaris.org/os/project/dtrace-chime/new_displays[+add new displays+] without recompiling. Displays are described in XML. A placeholder syntax allows DTrace program values to be substituted behind the scenes, enabling the user of Chime to select from a described range of program modifications without having to know about DTrace. The resulting modified programs are displayable, making the tool educational as an added benefit. Chime can function as a toolkit of canned displays, but also leverages some of the dynamic potential of DTrace to answer unanticipated questions prompted by the current display.

The NetBeans DTrace GUI Plugin is architected in such a way that you can easily extend and customize it.

The GUI package consists of two components: The NetBeans plugin (includes Chime) and the  ``DTraceScripts``  directory.

* The NetBeans DTrace GUI Plugin can be installed easily into the Sun Studio IDE, NetBeans IDE 6.0, NetBeans IDE 6.1, or NetBeans IDE 6.5.

* The  ``DTraceScripts``  directory contains several subdirectories. Each subdirectory contains several D scripts. The D scripts are categorized mostly based on DTrace providers. You can copy a new D script to an existing subdirectory from the shell command line, you can copy it into a newly created subdirectory in the  ``DTraceScripts``  directory. You can also create and save a new D script from within the IDE. Chime displays are included in the DTraceScripts directory.

== What is DTrace?

DTrace is a comprehensive tracing facility built into the Solaris^TM^ Operating System that can be used by developers and administrators on live production systems to examine the behavior of both user programs and of the operating system itself.

DTrace enables you to explore your system to understand how it works, track down performance problems across many layers of software, or locate the cause of aberrant behavior.

DTrace helps you understand a software system by enabling you to dynamically modify the operating system kernel and user processes to record additional data that you specify at locations of interest, called probes.

A probe is a location or activity to which DTrace can bind a request to perform a set of actions, like recording a stack trace, a timestamp, or the arguments to a function.

Probes are like programmable sensors scattered all over your Solaris system in interesting places. If you want to figure out what's going on, you use D scripts to program the appropriate sensors to record the information that is of interest to you. Then, as each probe fires, DTrace gathers the data from your probes and reports it back to you.

For more information, see link:http://www.sun.com/software/solaris/observability.jsp[+Observability+]


== System and Software Requirements and Downloads

The system and software requirements are listed below:

* The DTrace GUI plug-in is supported only on the Solaris^TM^ 10 08/07 Operating System and later Solaris 10 OS updates, and the OpenSolaris^TM^ Operating System.
* The NetBeans DTrace GUI Plugin runs with both the Sun Studio IDE and NetBeans IDE.
* NetBeans IDE 6.0, NetBeans IDE 6.1, or NetBeans IDE 6.5 can be downloaded from link:https://netbeans.org/[+https://netbeans.org/+] web site.
* The Sun Studio IDE can be downloaded from link:http://developers.sun.com/sunstudio/downloads/[+http://developers.sun.com/sunstudio/downloads/+] web site.


== The Rules of Engagement

* Your privileges need to be set in the  ``/etc/user_attr``  file. For example, the following is how DTrace privileges are set in the machines on which I run DTrace:

[source,bash]
----
nassern::::defaultpriv=basic,dtrace_user,dtrace_proc,dtrace_kernel,proc_owner
----

You have to log out from your system completely. These privileges take effect when you log in to the system.

User privileges are described in the security section of the article link:http://docs.sun.com/app/docs/doc/820-4221[+_Using DTrace with Sun Studio Tools to Understand, Analyze, Debug, and Enhance Complex Applications_+].

* If you have given yourself the Primary Administrator or root privileges, the DTraceScripts directory will be installed in root directory. See the example below:

[source,java]
----

    nassern::::profiles=Primary Administrator;roles=root;defaultpriv=basic,dtrace_user,dtrace_proc,dtrace_kernel
----
* Remove or rename the DTraceScripts directory if it is already installed from the previous releases of the DTrace GUI Plugin.
* The DTraceScripts directory will be installed automatically during the installation of the DTrace GUI Plugin.
* If you will be running the IDE as yourself, the  ``DTraceScripts``  directory will be installed in your home ($HOME) directory. If you will be running the IDE as root, the  ``DTraceScripts``  directory will be installed in the root directory.


== How to Install the NetBeans DTrace GUI Plugin

1. Start up NetBeans IDE or Sun Studio IDE.
2. Choose Tools > Plugins.
3. On the Available Plugins tab of the Plugins window, click the checkbox for DTrace to add a checkmark. (If DTrace does not appear in the available plugins list, click Reload Catalog and try again.) Click Install.

image::../../../images_www/articles/ide/dtracegui/install60.1.png[title="Available Plugins tab"]

[start=4]
. In the NetBeans IDE Installer window, click Next. 

image::../../../images_www/articles/ide/dtracegui/install60.2.png[title="NetBeans IDE Installer"]

[start=5]
. Accept the License Agreement and click Install.
. Click Finish.
. Close the Plugins window.

The NetBeans DTrace GUI Plugin is now installed into the NetBeans IDE or Sun Studio IDE.

Your installation of the DTrace GUI Plugin is now complete. To open the DTrace GUI, choose Window > DTrace.

The DTrace GUI Plugin is also available for download from link:http://plugins.netbeans.org/[+ ``http://plugins.netbeans.org`` +].


== How to Run the D Scripts in DTrace GUI Environment

To run D scripts in the DTrace GUI:

1. Start up the Sun Studio IDE, or NetBeans IDE.
2. Choose Windows > DTrace. The DTrace tab opens on the left side of the IDE.
3. Select the Toolkit tab. Select a D script from the Category list box in the DTrace panel and click Start.
4. The output of the selected D script is displayed in the Output window. Some scripts do not generate any output until you click Stop (red icon).

image::../../../images_www/articles/ide/dtracegui/Screenshot1.png[]

* You can run multiple D scripts simultaneously.
* Clicking Re-Run (green icon) runs the D script in the same Output tab.
* Clicking Stop (red icon) stops the D script that is associated with the Output tab.
* To save the output of a script, right-click in the Output window and choose Save As.


=== View, Edit, or Create a New D Script

You can double clicks on a D script to display the selected D script in the Editor window. Or you may right click on the selected D script and choose the View/Edit option from the Popup menu to display the D script in the Editor window.

To create a new D script:

1. Click New Script.
2. In the New Script dialog box, type the name of the new D script. The empty D script will be created in the selected category (directory). The following example shows how to create an empty  ``hello``  D script in the  ``Proc``  directory. 

image::../../../images_www/articles/ide/dtracegui/Screenshot2.png[]

[start=3]
. The newly created (empty)  ``hello.d``  script appear in the Editor window.
. Enter the code for new D script in the Editor window and save the file. The following example shows the DTrace code for the  ``hello.d``  script. 

image::../../../images_www/articles/ide/dtracegui/Screenshot3.png[] 

You can run the newly created  ``hello.d``  script from the DTrace GUI.

The configuration panel lists optional parameters that you can specify for each selected D script.

|===
|Pid |The process-id of the running process 

|Script Args |The D script arguments 

|Executable |The absolute path name to the executable 

|Executable Args |The executable arguments 
|===

In order to create the persistent data, the user specified parameters or properties are stored in a  ``.xml``  file. The property file has the same name as the D script file, with the exception  ``.xml``  extension. In other words, the user data is preserved for the subsequent invocation of D scripts and the IDE itself.

The following example shows how to run the  ``memleak.d``  script. The  ``memleak.d``  script can be used to detect memory leaks in applications. The  ``memleak.d``  script requires two parameters: The absolute path name to the executable and the D script module name. In the example,  ``/home/nassern/test/umem/hello``  is the absolute path name to the executable and  ``libc``  is the module name.

image::../../../images_www/articles/ide/dtracegui/Screenshot4.png[]

== DTrace Output Visualization with Chime

Chime is a graphical tool for visualizing DTrace aggregations. It displays DTrace aggregations using bar charts and line graphs. 

By default, Chime provides twelve display traces that can be selected from the list menu. The display traces can be used to monitor both the behavior of the Solaris kernel and applications that are currently running on the system. Users can visualize performance of functions that are defined in an application or they can visualize the kernel activities such as interrupt statistics, system calls, kernel function calls, and device I/O. 

One of the most useful features of Chime is ability to turn on recording while DTrace is collecting data about the application and the system. The recorded data can be played back at a later time to diagnose the cause of failure or performance degradation. The recorded data can be sent to other users who have access to NetBeans DTrace GUI Plugin or Chime for further investigation.

Steps to visualize the output of  DTrace aggregations: 

1. Select Chime tab. 
2. Select a display from the list of traces and press the Run button.

image::../../../images_www/articles/ide/dtracegui/Screenshot5.png[]


=== Adding New Chime Displays

An important feature of Chime is the ability to add new displays without re-compiling. A new display can easily be created by using Chime Display link:http://opensolaris.org/os/project/dtrace-chime/new_displays/wizard/[+Wizard+]. Simply, click on the Create a New Display icon to invoke the New Display Wizard. The New Display Wizard will guide you through steps to create a new display.

image::../../../images_www/articles/ide/dtracegui/Screenshot6.png[]

=== Add Drilldown

Drilldown lets you answer questions about values of interest. For example, for a selected executable you could get a breakdown of its system calls by function. Click link:http://opensolaris.org/os/project/dtrace-chime/new_displays/wizard/drilldown[+here+] to continue this walk-through by adding drilldown to your new display.


== List Probes Window

Users can query for the list of available Providers, Modules, Functions, or Probes using the List Probes window. To open the List Probes window, click the List DTrace Probes icon.

image::../../../images_www/articles/ide/dtracegui/Screenshot7.png[title="List Probes Window"]