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 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}
  ...
}

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:

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

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

Type

Default

Description

confirmonexit

Boolean (0 or 1)

 

1

Whether to confirm before exiting VSD, Main > Confirm Exit

def:sortbytype

Column label

Type

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

def:sortdecreasing

Boolean (0 or 1)

1

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

combineFiles

Boolean (0 or 1)

0

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

combineInstances

Boolean (0 or 1)

0

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

filelist

list of strings

empty list

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

noFlatlines

Boolean (0 or 1)

0

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

showCtrInfo

Boolean (0 or 1)

0

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

singleFileMode

Boolean (0 or 1)

1

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

templatesUseSelection

Boolean (0 or 1)

0

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

Type

Default

Description

absoluteTSMode

Boolean (0 or 1)

1

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

activecolor

string

red

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

def:linestyle

linear | step |

natural | quadratic

linear

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

def:showcrosshairs

Boolean (0 or 1)

0

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

def:showcurxy

Boolean (0 or 1)

1

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

def:showgridlines

Boolean (0 or 1)

0

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

def:showlegend

Boolean (0 or 1)

1

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

def:showlinestats

Boolean (0 or 1)

1

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

def:showminmax

Boolean (0 or 1)

0

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

def:xaxis:showtitle

Boolean (0 or 1)

1

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

def:xformat

date | time | elapsed

time

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

def:yaxis:showtitle

Boolean (0 or 1)

1

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

def:y2axis:showtitle

Boolean (0 or 1)

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

Type

Default

Description

wv:statmoninterval

integer

20

Monitor window, default statmonitor sample interval

wv:statmonflush

integer

0

Monitor window, number, default statmonitor flush interval

wv:statmonargs

list of options

empty list

Monitor window, the list of statmonitor arguments.

wv:statmoncompress

Boolean (0 or 1)

0

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.

TYPE is one of the following:

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.

svalue64
Signed 64-bit value.

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.

float
Floating point value.

LEVEL is one of the following:

common
advanced
wizard

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