3. VSD Template and configuration files
The first time you use VSD, the executable creates default template files and configuration files in the VSD home directory. These files are used on subsequent executions; this allows it to remember window sizes and locations, aliases, 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.
The VSD home directory is, by default, /home/username/ on UNIX and c:\users\username\ on Windows. If you set the environment variable $VSDHOME or %VSDHOME% in the environment before starting the executable, this directory is used instead of the user’s home directory.
3.1 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 that are located the VSD home directory.
There are two files that together manage the parameters that control what you see on startup: .vsdconfig and .vsdrc.
$VSDHOME / %VSDHOME%
The VSD home directory is, by default, the home directory of the user starting VSD. You may define an environment variable, VSDHOME, to specify a directory. This will override the default location for the configuration files.
To determine the exact locations of the files that were read by running VSD, see the About VSD window, opened from Main Window Help > About VSD... menu item. The Files: section includes the full path to all files associated with the currently running VSD.
.vsdconfig
This file, by default, contains a small number of system definitions. This file is created by VSD if it does not exist; VSD never writes updates to this file.
You may use a text editor to add settings. 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 default to write data files in a specific directory, regardless of what is in .vsdrc or what was done during in previous VSD monitoring.
If you delete the .vsdconfig file, then the next time VSD is started, the file will be recreated with default values.
.vsdrc
This file is used by VSD to record modifications to the display options, including menu selections and window locations and sizes. VSD reads this file when it starts up, 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 defaults from the VSD executable. When VSD subsequently exits, the .vsdrc file will be recreated with the current settings from the executable.
Note that VSD reads and applies settings specified in both .vsdconfig and .vsdrc. The setting in .vsdconfig overrides the same setting read from .vsdrc. If VSD writes .vsdrc on exit, it will update the values written to .vsdrc with the values that were read from .vsdconfig. If you configure VSD to not write the .vsdrc on exit, you may configure VSD at both levels, .vsdconfig and .vsdrc, without being affected by transient changes when VSD is executed. This provides additional flexibility in managing general settings such as aliases as well as individual settings such as preferred window layouts.
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.
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, Chart window, Statics info, and other dialogs 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.
There are a number of other dialog that have similar settings.
3.2 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 the VSD home directory if it does not already exist in that location.
If you delete the .vsdtemplates 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 be used, to mean 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.
’*’ can be used to match multiple process names.
’!’ can be use to exclude specific processes by name. For example,
{Stn {!pagemgrThread} ...
matches all Stone processes whose name does not include ’pagemgrThread’.
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.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.
uvalue64
Unsigned 64-bit value.
LEVEL is one of the following:
While the LEVEL field remains in the records, it has no effect in VSD v5.5.3 and later versions.
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.