Adding New Traces
en

Adding New Traces

Adding New Chime Traces

Contents

Overview

To add a new Chime trace, you need to describe the trace in XML as a set of properties recognized by Chime. Chime provides a wizard as well as command line options to generate the XML for you, and trace properties are documented here in case you need to edit the XML by hand. Once you add a Failed to execute the [code] macro description to /opt/OSOL0chime/displays, Chime will pick it up automatically and add an entry to the Traces list in the main window. Subdirectories under the displays directory are also loadable from the Chime menu and the Categories pulldown, so you can group traces in your own categories and subcategories.  A special file, description.xml may be included in any subdirectory to specify the directory properties, such as a name for the group of traces included in that subdirectory (other than the directory name, which is used by default), text to describe the group of traces, a mnemonic for the menu item that accesses the traces, and the order in which the traces should be listed (if unspecified, traces are listed alphabetically by title).  

Chime comes installed with a set of traces that you are free to change (although you may want to save the originals in a separate directory).  

Chime main window

Alternatively, you can create your traces in any directory specified on the command line with the -d option, and Chime will treat the specified directory as if it were the displays directory.  

To see trace creation in action, you can watch this screencast (22 min 28 sec) that introduces Chime and demonstrates how to use it.  

For a good introduction to DTrace, I found Bryan Cantrill's Demo'ing DTrace blog very helpful, and good for an occasional re-read.  
  

Adapting an Existing DTrace Program

There are few important observations to make about your DTrace program:

  1. Since Chime is a tool for visualizing DTrace aggregations, it follows that your program must include at least one aggregation.  See the Aggregations chapter of the Solaris Dynamic Tracing Guide for details about DTrace aggregations.
  2. If you use the printa() action on an aggregation, that aggregation will thereafter be unavailable to Chime.  Typically, printa() is found in a profile probe such as tick-1sec.  You should delete these tick clauses from your program.  Instead of printing your aggregations, you are now relying on Chime to display them.
  3. You can have multiple aggregations in your program.  However, Chime assumes that all aggregations in the same program share the same tuple (aggregation key), or at least almost the same: you can specify two different tuples, A and B, such that B starts with A. For example: @[execname] and @[execname, ppid].   If two aggregations in your program have completely different tuples, the results in Chime are currently undefined. 

For examples of scripts from the DTraceToolkit, see the following blog entries:  

Chime and the DTraceToolkit  
Chime and the DTraceToolkit, Part 2  

New Trace Wizard

Chime provides a wizard to create or edit trace descriptions. You can access the wizard from the menu (File \| New Trace ...), the New Trace Wizard Toolbar Button toolbar button, or by using the -W command line option.  

See the New Trace Wizard page for details, including an example walk-through.  

Generating Traces On The Command Line

Chime will generate traces dynamically on the command line if you specify a program that meets the criteria listed above. The program may be specified as a string using the -n option or as a file using the -s option, just as with the dtrace(1M) command. You can even specify DTrace options for the trace using -x name=value and -Z, just as you would with dtrace(1M). The column headers will be generated automatically from the aggregation key and the aggregation names in your program, although you can specify your own column headers using the -H option followed by a comma-separated list in quotes. The -T option specifies a title to appear in the display's title bar.  

See the Command Line page for details.  

XML Properties

You can also specify trace properties by hand in the display's Failed to execute the [code] macro description file. Here's a simple example to get you started; you can find other (less simple) examples installed in the /opt/OSOL0chime/displays directory.

See the XML Properties page for a complete description of each available property.

Back to Chime | Back to top

Tags:
Created by admin on 2009/10/26 12:13
Last modified by Tom Erickson on 2011/01/05 01:05

Collectives

Project dtrace-chime Pages

XWiki Enterprise 2.7.1.34853 - Documentation