3. VSD Template and configuration files

Previous chapter

Next chapter

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, the statistic level you have selected, 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.

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.

There are two files that together manage the parameters that control what you see on startup.


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.


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 it subsequently exists, the file will be recreated with the current settings.

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

for example:

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.

Parameter name





Boolean (0 or 1)



Whether to confirm before exiting VSD, Main > Confirm Exit


Column label


On file load, the column to use to sort processes.


Boolean (0 or 1)


On file load, the direction of sort for the process list; 0 is decreasing, 1 is increasing.


Boolean (0 or 1)


Whether to combine values for all selected processes in all open files when displaying a statistic; Main > Combine Across Files


Boolean (0 or 1)


Whether to combine values for all selected processes when displaying a statistic; Main > Combine


list of strings

empty list

List of filenames displayed in the Main Window File: dropdown.


Boolean (0 or 1)


Whether to show statistics for a process if all values for that statistic are zero; Main > No Flatlines


Boolean (0 or 1)


Whether to have the Statistics Information window open. Main > Show Statistics Info


Boolean (0 or 1)


Whether working with multiple data files is allowed. Main > Single File Mode


Boolean (0 or 1)


Whether the template applies only to the selected processes.

Chart Window Display Options

The following parameters describe the defaults for including and omitting information from chart windows.

Parameter name





Boolean (0 or 1)


Whether to use absolute timestamps for charts. Main > Absolute Timestamps




The color of the selected line on a chart. Chart > Selected Line Color...


linear | step |

natural | quadratic


How the line is rendered on charts; Chart > Default Line Style


Boolean (0 or 1)


Whether to show cursor crosshairs on charts, Chart > Show CrossHairs


Boolean (0 or 1)


Whether to show current X and Y values on a chart; Chart > Show Current Values


Boolean (0 or 1)


Whether to show gridlines on charts, Chart > Show Grid Lines


Boolean (0 or 1)


Whether to show the legend (the process and statistic name and line color for the chart lines) on charts; Chart > Show Legend


Boolean (0 or 1)


Whether to show text with points, min, max, mean, and standard deviation on graph; Chart > Show Line Stats


Boolean (0 or 1)


Whether to show max and min values on chart menu bar; Chart > Show Max and Min


Boolean (0 or 1)


Whether to display label on x axis, Chart > Show Time Axis Title


date | time | elapsed


How to display the time on the x-axis of a chart; Chart > Time Format


Boolean (0 or 1)


Whether to display y axis label on left side, Chart > Show Left Axis Title


Boolean (0 or 1)


Whether to display y axis label on right side, Chart > Show Right Axis Title

Monitor Window Options

The following parameters apply to the Monitor window, describing options for how to start statmonitor.

Parameter name







Monitor window, default statmonitor sample interval




Monitor window, number, default statmonitor flush interval


list of options

empty list

Monitor window, the list of statmonitor arguments.


Boolean (0 or 1)


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.

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}

For example:

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:

type — One of the following:


‘+’ 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:


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:
with the following information:

STATNAME is the name of the statistic.

TYPE is one of the following:

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.

64-bit counter. Similar to counter, but used when the values can become extremely large.

Signed 32-bit value. If data values read from a file are larger than 32 bits, it is automatically promoted to a 64 bit.

Signed 64-bit value.

Unsigned 32-bit value. If data values read from a file are larger than 32 bits, it is automatically promoted to a 64 bit.

Floating point value.

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.

Previous chapter

Next chapter