OpenSolaris

1. Project: Chime Visualization Tool for DTrace
   1. Installation
   2. Change Log
      1. Known Issues
   3. Displays
   4. Adding New Displays
      1. New Display Wizard
         1. Adding Drilldown
      2. Command Line
      3. XML Properties
   5. Java DTrace API
      1. jdtrace Example
   6. Announcements
   7. Discussions
   8. Leaders
   9. Observers
   10. Blogs
   11. Articles

New Display Wizard

Chime displays are described in XML (see Adding New Displays), and a wizard is provided to generate that XML for you. You can access the wizard from the menu (File | New Display ...) or directly from the command line with the -W option. Use the wizard to create new displays or edit existing ones.

Let's say you want a display to monitor system calls per second made by each executable on the system. The following walks you through the steps of creating such a display:

Walk-Through (System Calls Example)

• Set Title and Output File
• Set DTrace Program
• Set Cleared Aggregations
• Specify Columns
  • First Unspecified Column
    • Specify Column Data
    • Set Column Properties
  • Next Unspecified Column
  • Aggregation Value Column
• Test Run the Display
• Provide a Description
• Finish Creating the Display
• Add Drilldown

Set Title and Output File

When the wizard appears, you will see the default title "Display" highlighted in the Title field.

Type "System Calls" and press Enter to proceed to the next step.

Set DTrace Program

Click in the text pane under the Program String radio button and enter the following DTrace program:

You can click the Check Compile button to make sure you typed the program correctly. If there is a syntax error, you will see a red 'X' instead of a green check mark, and there will be a hyperlink to view details about the error. For help adapting DTrace programs to Chime, click on the Help button. To learn about writing DTrace programs with aggregations displayable in Chime, a good place to start is the Aggregations chapter of the Solaris Dynamic Tracing Guide.

Press Alt-N (or click the Next button) to proceed to the next step:

Set Cleared Aggregations

In this step you specify whether or not you want running totals. By default, Chime clears all aggregations, resetting their values to zero, each time it gets the latest snapshot of aggregate data. Since we want to display system calls per second, the default behavior (no running totals) is the right choice. Simply proceed to the next step.

Note that if your program included other aggregations, they would show up here, each with its own check box. For example, if your program included the statement @counts[execname] = count(); then "counts" would also appear in the list of individually clearable aggregations.

Specify Columns

Here we list all the columns by name as they will appear in the display's column header from left to right. It helps to picture the table you want to display. In this case, we want a display similar to the "System Calls" display installed with Chime:

• An "Executable" column, right aligned
• A "History" column with a sparkline
• A renamed "Calls Per Second" column, left aligned

The basic idea is to include one column for each element of the aggregation key followed by a column for the aggregation values. Since we are aggregating @[execname] = count(); we need one column for the execname key followed by one column for the count() values. If we were instead aggregating @[execname, probefunc] = count(); we would need two key columns, one for execname and one for probefunc, followed by one value column for count(). In this case, we only need two columns: "Executable" for the execname key and "Calls Per Second" for the count() values. However, we insert an additional "History" column to provide a sparkline view of the data in the "Calls Per Second" column over time.

Type "Executable" and press Enter to add a new empty row. Type "History" and press Enter again. When you finish typing "Calls Per Second" (with or without pressing Enter) you can click Next to proceed to the next step.

First Unspecified Column

Specify Column Data

Here we specify the first unspecified column, "Executable". To start, we simply need to indicate whether the column displays an aggregation key (such as execname in @[execname] = count();) or an aggregation value (such as count() in @[execname] = count();). A third type of column, the Alternate View (see below) is special: it takes source data from another column (or columns) and presents that data differently. The "History" column is an example of an alternate view.

In this case our job is easy. The screen already indicates Tuple Member (a member of an aggregation key) with Tuple Index 0 (the first element in square brackets). That corresponds to execname in @[execname] = count(); exactly what we intend. Simply click Next.

Set Column Properties

This step allows us to set properties appropriate for a column that displays part of an aggregation key.

As before, we could simply click Next. However, a totals row would be nice, and it's not much trouble. Choose "Count" from the Total pulldown and specify the singular and plural forms of the units label. Type "executable" in the Singular Total Label field. What you type is echoed in the Plural Total Label field, so all you need to do is press Tab followed by s to complete the plural form. If, instead of @[execname] = count(); we were aggregating @[execname, probefunc] = count();, then the "Executable" values would repeat within the column, so we would need to choose "Unique Count" rather than "Count" to display the number of unique executables.

We also want to right-align the executable names so they are easier to associate visually with their count() values in the columns to the right. Choose "right" from the Alignment pulldown.

Now click Next.

Next Unspecified Column

Now we repeat steps 4a. Specify Column Data and 4b. Set Column Properties for the "History" column. The green check at the top of the screen indicates that we have successfully specified the previous "Executable" column.

This time, the screen initially indicates Tuple Member with a Tuple Index of 1 (auto-incremented from the tuple index of the previous "Executable" column). This does not correctly indicate the purpose of the "History" column. Choose "Calls Per Second" from the Source Columns pulldown. This automatically selects the Alternate View radio button.

Click Next.

Sparkline is already selected. The "History" column will present an alternate view (over time) of the count() data from the "Calls Per Second" column using a sparkline graph (see Edward Tufte's Sparklines page.)

Click Next and proceed to the last unspecified column.

Aggregation Value Column

The last column, "Calls Per Second", displays the values of the count() aggregating action. As before, the initial selection in this screen is Tuple Member, which we need to change, since this column does not display part of the aggregation key.

Select Aggregation Value and leave the Aggregation Name field empty since the aggregation in our DTrace program is unnamed: @[execname] = count(); (@ is the anonymous aggregation).

Click Next.

Columns that display aggregation values have more properties to specify than columns that display aggregation keys:

Check Value Per Second.
Choose "left" in the Alignment pulldown.
Choose "#,##0" in the Format pulldown, indicating thousands separators.
Scroll down ...

Choose "Sum" from the Total pulldown.

Click Next.

Once all the columns have been specified, we return to step 4. Specify Columns to confirm the intended list of columns before moving on.

The green check marks indicate which columns have been specified (all of them). Again, the columns are listed in the order they will appear from left to right in the display. We also see some new indicators: "[0]" after "Executable" is like an array index indicating that the column displays the first member of the aggregation key. "( Calls Per Second )" indicates that the "History" column presents an alternate view of data from the "Calls Per Second" column. "@" indicates that the "Calls Per Second" column displays aggregation values from the anonymous aggregation. If the aggregation had instead been named @counts in our DTrace program, we would see "@counts" here instead.

If you want to make any corrections, you can select any of the listed column names and click the Specify > button to redo steps 4a and 4b for that column, or click Specify >> to redo only step 4b. Afterwards you will again return to the column list (above) to confirm your specifications before moving on.

Click Next.

Test Run the Display

Having all the columns specified, we could have clicked Finish instead, but why not test the display first to see if does what we intended? This step lets us do just that:

Click the Run Display button. Another window will appear with a display that should look something like this:

By default, the display is sorted in ascending order by the aggregation key. Click on the "Calls Per Second" column header to sort by value descending. How you set the sort during the test run determines the initial sort of the created display. We could also change the initial window size, but the default seems like a good size.

If you find that you need to make some corrections, click on the Back button to revisit any of the previous steps. You can leave the test display running so that it is available for side-by-side comparison when you return to this screen for an updated test run.

This test display improves on the installed "System Calls" display by adding a totals row and a better initial sort. You can close it and click Next in the wizard to provide a description.

Provide a Description

Whatever text you enter to describe the display appears in the Description pane in the main Chime window when the new display is selected in the Traces list. You can use HTML to specify things like bold, italic, underline, font, and numbered or bulleted lists.

Above is a fancifully obtuse description that serves to illustrate the formatting possibilities just listed (although the point about the cyan scale indicator might actually be helpful). Here is the resulting description as it will appear when the display is selected in the main Chime window:

Click Next.

Finish Creating the Display

The next step adds drilldown support. It is evidently disabled, and the explanatory paragraph is intended to make clear that our DTrace program is not written in the way required to support drilldown.

We could use the Back button to remedy this, but that's a long way to back up, so it's probably easier to finish what we have and reopen it later at step 1, only one step away from our DTrace program.

Click Finish. You should see the following console output:

Wrote /opt/OSOL0chime/displays/new/system_calls.xml
To run, enter "/opt/OSOL0chime/bin/chime -C /opt/OSOL0chime/displays/new/system_calls.xml".

Besides running the display directly from the command line, you can also load newly created displays from the Trace Group pulldown of the main Chime window:

New displays are put in /opt/OSOL0chime/displays/new by default, where they are accessed by the menu item pictured above. If this is the first time you have created a new display, congratulations! You will see the following list with your one new display:

You can move the .xml descriptions to /opt/OSOL0chime/displays or another of its subdirectories later as you find out which new displays are useful. In that case, if you specified the DTrace program as a file with a relative pathname, you may need to update that pathname relative to the new location.

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 here to continue this walk-through by adding drilldown to your new display.