3. VSD Template and configuration files
The first time you use VSD, the executable creates default template files and configuration files in your home directory. These files are used on subsequent executions; this allows it to remember the statistic level you have selected, window sizes and locations, and similar details.
You can delete these file at any point, and they will be recreated from the default the next time you use VSD.
3.1 VSD Chart Templates
VSD templates specify a set of processes and statistics that together represent a useful picture of one behavior of the system. VSD is shipped with a set of predefined templates. As described under Using and Creating Templates, you can open charts on these templates, and create your own templates based on charts you have constructed.
To further customize the templates you use, you may want to edit the templates directly. The templates are stored in a text file using specific syntax. This section provides information you need if you wish to edit the template files directly.
VSD Templates File
The default templates are in the file .vsdtemplate, which is written to your home directory the first time you start up VSD.
If you delete the .vsdconfig file, then the next time VSD is started, the file will be recreated with default values.
Template Syntax
The template files are written in a formatted form that is understood by the TCL code that supports VSD.
Templates in the .vsdtemplate have the following form:
set vsdtemplates(TemplateName) {
{Type {ProcessName} StatName scale filter axis}
{Type {ProcessName} StatName scale filter axis}
...
}
set vsdtemplates(Garbage) {
{Stn {*} PagesNeedReclaimSize 1 none y2}
{Stn {*} ReclaimedPagesCount 1 none y2}
{Stn {*} EpochGcCount 1 persecond y}
{Stn {*} ReclaimCount 1 persecond y}
{Gem+ {*Gc*} CommitCount 1 persecond y}
}
set vsdtemplates(CacheTooSmall) {
{Shrpc ShrPcMonitor FreeFrameCount 1 none y2}
{+ {*} FramesFromFreeList 1 persecond y}
{+ {*} FramesFromFindFree 1 persecond y}
}
The data for each line in each template includes:
StnShrpcGemPgsvr
‘+’ can also be used, which means that all processes that match this line spec will be combined into a single line. + can be used either standalone, meaning all process types, or added to a type name. For details on types, see here.
name — Identifies the specific process by process name. You m.ay use * to match multiple process names. For more on process names, see here.
stat — The name of a specific existing statistic.
scale — The number of the scale for this particular statistic. It will usually be 1. For more details on scales, see Scaling.
filter — The name of the filter, which will be one of the following:
none
persecond
persample
aggregate
For details on these filters, see Filters
axis — Either y, the left axis, or y2, the right access. Units for this statistic line are labeled on the specified side y-axis.
Once you have created or edited your template file, save the .vsdtemplates file, and use the menu item Chart > Reload Template File to load this file. If you have made syntax errors, reload will report and error and the file will not load.
For more about VSD templates and the syntax and options available, see the VSD help under the topic “Template Syntax”.
3.2 VSD Configuration Files
VSD provides a number of display options, which are set by menu items in vsd. These options are recorded in platform-independent text files in your home directory.
There are two files that together manage the parameters that control what you see on startup.
.vsdrc
This file is used by VSD to record modifications to the display options, including menu selections and window locations and sizes. VSD reads the file when it starts, and by default, writes the file when it exits, so the next time you open VSD it will have the same settings.
If you delete the .vsdrc file, VSD will start with defaults from .vsdconfig or from the VSD executable. When it subsequently exists, the file will be recreated with the current settings.
If you would like VSD to always start with a fixed set of display options, rather than continuing with the settings from the previous VSD execution, you can disable saving changes on exit. This is done by unchecking the Main Window’s menu item Main > Save Options On Exit. To make this setting persistent, you must also execute the Main > Save Options.
.vsdconfig
This file may contain the same set of VSD settings as the .vsdrc, however, VSD never writes updates to this file. By default, it contains a small number of system definitions.
You may use a text editor to add settings, or copy settings from the .vsdrc file. Any settings in this file override the same definition in .vsdrc. This provides another level of customization for the various default settings. For example, if you set
set vsd(wv:statmonargs) {-d $GEMSTONE/statmons}
It ensures that the monitor window will always write data files in a specific directory, regardless of whether Save Options On Exit is enabled or not.
If you delete the .vsdconfig file, then the next time VSD is started, the file will be recreated with default values.
Configuration file format
In most cases, you can configure your default display by taking advantage of the natural way VSD saves your settings to .vsdrc and reads them on restart. By doing this, you get a consistent display without any extra work.
However, if you want to set a configuration that is always used, regardless of what you do during any particular VSD session, you will need to edit the VSD configuration file .vsdconfig. The configuration file format is the same in .vsdconfig and .vsdrc, so you may copy lines between files.
The following sections document many of the relevant configuration parameter names and meanings.
Configuration options are specified in a format that is specific to VSD/TCL, and are not intended for general use by customers.
To include a comment line, prefix the line with #.
Incorrect configuration names and settings encountered in reading the files are ignored; default values will be used in this case.
Configuration options have the format:
set vsd (configurationOption) value
set vsd(confirmonexit) 1
Acceptable value arguments depend on the parameter. Many are Integers, but some parameters are strings. Lists are indicated by {}. Boolean statistics are specified as 0 or 1.
Main Window options
The following statistics relate to the main VSD window.
Chart Window Display Options
The following parameters describe the defaults for including and omitting information from chart windows.
Monitor Window Options
The following parameters apply to the Monitor window, describing options for how to start statmonitor.
|
Monitor window, default for if statmonitor should write compressed file |
Window locations and display
The location, size, and proportion of the Main Window, the Chart window, and the Statics info file are recorded.
def:geometry sets the size and location of the main window.
instancePaneSize sets the height of the Process pane in the main window.
statisticPaneSize sets the height of the Statistics pane in the main window.
geometry:.datawin sets the size and location of the chart window.
geometry:.ctrinfo sets the location of the statistics information window.
Fonts
Window title, menu, and other fonts are based on operating system default fonts, and are not controllable. However, you may set the font for charts and help text.
Chart window text fonts
The VSD declarative smallfont is a list of font attributes that controls what is used to display text on a chart windows. This configuration is used for most text on a chart: legend, axis labels, summary information, etc. Attributes include the font family, size, weight, slant, underline and overstrike . These can be set using Chart > Choose Chart Font.... For example,
set vsd(smallfont) {-family fixed -size 12 -weight normal
-slant roman -underline 0 -overstrike 0}
Help window text fonts
The VSD declarative textfont is a list of font attributes that controls what is used to display text in the online help windows. Attributes include the font family, size, weight, slant, underline and overstrike. These can be set using Help > Choose Text Font.... For example,
set vsd(textfont) {-family fixed -size 10 -weight normal
-slant roman -underline 0 -overstrike 0}
3.3 Data in VSD TCL files
The VSD distribution includes a file containing information about all statistics that VSD expects to encounter. This includes statistics names and information that impacts how the values are handled in VSD.
For each statistic, there is a line of the form:
{STATNAME} {TYPE LEVEL UNITS IS_FROM_OS}
with the following information:
STATNAME is the name of the statistic.
counter
32-bit counter. Counters are expected to start from zero or an arbitrary value and always increase. For counter types, the useful information is the changes between values over time, not the values themselves; for example, the number of times garbage collection has executed. Counter types have a default filter of per second. Also, for counter types "No flatlines" means the per-second value is zero; the unfiltered statistic value itself may be non-zero.
counter64
64-bit counter. Similar to counter, but used when the values can become extremely large.
svalue
Signed 32-bit value. If data values read from a file are larger than 32 bits, it is automatically promoted to a 64 bit.
uvalue
Unsigned 32-bit value. If data values read from a file are larger than 32 bits, it is automatically promoted to a 64 bit.
LEVEL is one of the following:
When VSD is configured to use a particular statistics level, statistics with higher levels are not displayed. For example, when VSD statistic level is set to Common Statistics only, advanced and wizard statistics are not displayed.
UNITS is a string that describes what the statistic measures (e.g., pages, operations, etc.). This is used to label the vertical axis.
IS_FROM_OS is "true" if the statistic comes from the operating system and is "false" if not.
Effect of statistic type on combined lines
VSD allows you to perform arithmetic operations between statistic lines. For example, it is useful to select a number of Gems processes and show the combined values of a statistic, such as the CommitCount for all the ReclaimGem processes.
For non-counter types, adding or combining is always a simple sum, in which the values for each process that includes a sample value at the given time are added together.
When one of the processes ends before the time of the final sample for all the processes, however, this is handled differently for statistics of counter type that are designed to be viewed per-second.
For statistics of counter type, on a chart that shows combined values, for processes that ended before the end of the chart display, the combined line continues to include the value of the final sample for any process that ends. This keeps the per-second graphs correct. If you examine the unfiltered combined data, however, this will appear incorrect.
If this adjustment was not made for counters, it would produce invalid decreases for the total after a process ended. For example, the per-second time spent waiting for IO by a set of processes is not actually decreased when one of the processes ends.