Wiki code for Adding New Displays

Hide Line numbers
1: == Adding New Chime Displays
2: === Contents
3: * [[Overview>>#Overview]]
4: * [[Adapting an Existing DTrace Program>>#Adapting_an_Existing_DTrace_Program]]
5: * [[New Display Wizard>>#New_Display_Wizard]]
6: * [[Generating Displays On The Command Line>>#Generating_Displays_On_The_Command_Line]]
7: * [[XML Properties>>#XML_Properties]]
8: 
9: == Overview
10: 
11: To add a new Chime display, you need to describe the display in XML as a set of properties recognized by Chime. Chime provides a [[wizard>>wizard]] as well as [[command line options>>cmdgen]] to generate the XML for you, and display properties are documented [[here>>xml]] in case you need to edit the XML by hand. Once you add a {{code}}.xml{{/code}} description to {{code}}/opt/OSOL0chime/displays{{/code}}, Chime will pick it up automatically and add an entry to the **Traces** list in the main window. Subdirectories under the {{code}}displays{{/code}} directory are also loadable from the Chime menu and the **Trace Group** pulldown, so you can group displays in your own categories and subcategories.  A special file, {{code}}description.xml{{/code}} may be included in any subdirectory to specify the directory properties, such as a name for the group of displays included in that subdirectory (other than the directory name, which is used by default), text to describe the group of displays, a mnemonic for the menu item that accesses the displays, and the order in which the displays should be listed (if unspecified, displays are listed alphabetically by title).  
12: 
13: Chime comes installed with a set of displays that you are free to change (although you may want to save the originals in a separate directory).  
14: 
15: ![Chime main window] (screens_a/chime.gif)  
16: 
17: Alternatively, you can create your displays in any directory specified on the command line with the {{code}}-d{{/code}} option, and Chime will treat the specified directory as if it were the {{code}}displays{{/code}} directory.  
18: 
19: To see display creation in action, you can watch this [[screencast>>http://frsun.downloads.edgesuite.net/sun/07C00941]] (22 min 28 sec) that introduces Chime and demonstrates how to use it.  
20: 
21: For a good introduction to DTrace, I found Bryan Cantrill’s [[Demo’ing DTrace>>http://blogs.sun.com/bmc/entry/demo_ing_dtrace]] blog very helpful, and good for an occasional re-read.  
22:   
23: == Adapting an Existing DTrace Program
24: 
25: There are few important observations to make about your DTrace program:
26: 
27: 1. Since Chime is a tool for visualizing DTrace aggregations, it follows that your program must include at least one aggregation.  See the [[Aggregations>>http://docs.sun.com/app/docs/doc/817-6223/6mlkidlh7?a=view]] chapter of the //Solaris Dynamic Tracing Guide// for details about DTrace aggregations.
28: 1. If you use the **printa()** action on an aggregation, that aggregation will thereafter be **unavailable to Chime**.  Typically, {{code}}printa(){{/code}} is found in a {{code}}profile{{/code}} probe such as {{code}}tick-1sec{{/code}}.  You should delete these {{code}}tick{{/code}} clauses from your program.  Instead of printing your aggregations, you are now relying on Chime to display them.
29: 1. 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. 
30: 
31: For examples of scripts from the [[DTraceToolkit>>http://www.brendangregg.com/dtrace.html#DTraceToolkit]], see the following blog entries:  
32: 
33: [[Chime and the DTraceToolkit>>http://blogs.sun.com/tomee/entry/chime_and_the_dtracetoolkit]]  
34: [[Chime and the DTraceToolkit, Part 2>>http://blogs.sun.com/tomee/entry/chime_and_the_dtracetoolkit_part]]  
35: 
36: == New Display Wizard
37: 
38: Chime provides a wizard to create or edit display descriptions. You can access the wizard from the menu (**File \| New Display ...**), the ![New Display Wizard Toolbar Button](wizard/screens_g/New16.gif) toolbar button, or by using the {{code}}-W{{/code}} command line option.  
39: 
40: See the [[New Display Wizard>>wizard]] page for details, including an example walk-through.  
41: 
42: == Generating Displays On The Command Line
43: 
44: Chime will generate displays 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 {{code}}-n{{/code}} option or as a file using the {{code}}-s{{/code}} option, just as with the {{code}}dtrace(1M){{/code}} command. You can even specify DTrace options for the display using {{code}}-x_name_=//value//{{/code}} and {{code}}-Z{{/code}}, just as you would with {{code}}dtrace(1M){{/code}}. 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 {{code}}-H{{/code}} option followed by a comma-separated list in quotes. The {{code}}-T{{/code}} option specifies a title to appear in the display’s title bar.  
45: 
46: See the [[Command Line>>cmdgen]] page for details.  
47: 
48: == XML Properties
49: 
50: You can also specify display properties by hand in the display’s {{code}}.xml{{/code}} description file. Here’s a [[simple example>>xml#A_Simple_Display_Example]] to get you started; you can find other (less simple) examples installed in the {{code}}/opt/OSOL0chime/displays{{/code}} directory.
51: 
52: See the [[XML Properties>>xml]] page for a complete description of each available property.
OpenSolaris

Top Menu

Wiki code for Adding New Displays

Search

Collectives

Community Group

Project

User Group

Subsites

Project dtrace-chime Pages
