1. VSD 5.4 Release Notes
Overview
Visual Statistics Display (VSD) version 5.4 is a new release of the VSD product.
This version of VSD, like previous versions, supports statmonitor files generated from:
Supported Platforms
VSD version 5.4 is verified and supported on the following platforms:
- Windows 7, Windows 2008 R2, Windows 8, Windows 10, and Windows 2012
- Solaris 10 and 11 on SPARC
- Solaris 10 on x86
- AIX 6.1 and AIX 7.1
- Red Hat Linux ES 6.4, 6.5, 6.7, 6.9, 7.1, and 7.4; Ubuntu 14.04 and 16.04; SUSE Linux Enterprise 12, on x86
-
OS X 10.11.2 (El Capitan) with Darwin 15.2.0 kernel, and
OS X 10.12.6 (Sierra), with Darwin 16.7.0 kernel, on x86
Changes in this release
Configuring location of startup files
VSD normally looks for .vsdconfig, .vsdrc, and .vsdtemplates in the home directory of the user executing vsd. Previously, this was not configurable; now, setting the environment variable $VSDHOME on Unix, or %VSDHOME% on Windows, causes VSD to look for and read, or create, these files in another directory.
If this directory is set in the environment in which VSD is started, and provided it is a valid directory, VSD will use that location instead of the home directory. If this environment variable is not defined or not a directory, VSD will continue to use the home directory.
Auto-updated rolling time window
When using the VSD auto update feature to continuously monitor a running system, details of the recent statistics become compressed and difficult to read as the monitoring session becomes long. The existing ability to zoom is not useful since as new statistics are added the zoomed section no longer shows the most recent records.
A new feature has been added to allow monitoring over a rolling time window, specified as a duration of hours, minutes, and seconds before the timestamp of the most recent record. With this configured, charts will display the most recent statistics for that duration, trimming off the left-hand (earlier) statistics in the chart. As manual or automatic updates add new statistics on the right, older ones will be trimmed on the left.
The keyboard shortcut Ctrl-R brings up this dialog from the Main Window.
Rolling left trim, like auto update, applies to the current file, and is specifically intended for the file created by Main > Monitor.... The current file is shown at the top of the Main window, in the field labeled File:. The name of the current file is displayed at the bottom of the dialog.
Using Apply updates the graphs for all open Chart Windows on statistics in the given file.
Managing Fonts
VSD now has the ability to set the fonts for the Main Window, as well as the fonts for the Chart Window, Data Log, and Help Text. These are now set using platform native Font selection UI.
The font for the main Window, which also sets the label and menu fonts for other windows, is set using the Main Window menu item Main > Choose Main Font....
The Chart menu Item Choose Chart Font... now includes options to get the Chart Window font and the data log font.
Hiding specific process types in the process list
You may now hide specific process types in the process list. For example, you may wish to not see the statistics associated with page servers or statmonitor itself.
A menu item as been added, Main > Hide Instance By Type...,which provides a list of process types that can be hidden.
Note that this setting is not saved to the .vsdrc, since applying this filter on a much later restart of VSD may unexpectedly conceal processes.
"Preferences" has been renamed to Settings, and Confirm Exit moved
The Main Window Main menu Preferences has been renamed to Settings, and the Confirm Exit menu item is now on this sub-menu.
"Elapsed Time In Seconds" has been renamed to "Seconds"
This menu item is on the Main Window Chart > Time Format and Chart Window Chart > Time Format submenus. The previous name was incorrect when in Absolute Timestamps mode.
Keyboard shortcuts to enable or disable auto update
With File > Auto Update enabled, VSD continuously monitors the loaded statmonitor file for added entries, and reads and updates the display with new information.
The shortcut shift-control-A now can be used to toggle Auto Update.
VSD recording further configuration information
Many configuration details are recorded in .vsdrc, and will be applied when VSD is next started with that .vsdrc. Some details in what has recorded have changed, such as the file filter (e.g. all files or only statmonitor files) in the Open Statmonitor File dialog. Other minor missing details are now recorded, and the entries in .vsdrc are now sorted.
VSD command line specification for a directory
VSD now accepts a single directory on the command line, in addition to one or more statmonitor file names.
If a directory is included on the command line, VSD uses that directory as its working directory, and after startup, opens the Open Statmonitor File dialog on this directory.
Aliases for statistic names
Both GemTalk Engineering and Customer applications make use of session statistics, which can be set programmatically in GemStone Smalltalk or in C code. Session statistics are recorded by Statmonitor and displayed in VSD for Gems as SessionStat00... SessionStat47. In addition, applications can update global statistics, reported in VSD for Stones as GlobalStat00..GlobalStat47.
To make analysis of the process-specific uses of these statistics easier, you may now add custom aliases, to associate the statistics with meaningful names and descriptions. Aliases appear in parenthesis after the statistic name.
The VSD distribution also includes alias templates for common GemStone server maintenance operations, such as backup and markForCollection.
Adding aliases is not limited to session statistics; any Gem or Stone statistic name may be associated with an alias for a particular process pattern. Statistics aliases are not applied for processes other than Gems or Stones.
Process-specific appended alias names
A custom statistics alias associates an alias name, description, and other details that VSD uses for display, with an existing statistic name. This association is set by a name pattern for the process (and, optionally, by GemStone version).
The aliases are defined via commands that are included in a VSD support file, either .vsdconfig or .vsdrc. To update an alias, you must shut down VSD, edit the file, and restart.
The setCtrAlias command has the following arguments:
setCtrAlias CacheNamePattern StatName Alias Type Filter Units Description [versionPatterns [writeToStartupFile]]
CacheNamePattern - cache name of processes to match, case sensitive.
StatName - name of an existing cache statistic
Type - one of counter, counter64, uvalue, uvalue64, svalue, svalue64.
Filter - one of none, persecond or persample.
Units - Unit of measure for the statistic.
Description - A brief description of the statistic.
versionPatterns (optional) - * for all GemStone versions, or a list of GemStone version numbers that the alias applies to. This is primarily intended for the system aliases described starting here.
writeToStartupFile (optional) - Boolean (1 or 0) indicating if the alias will be written to .vsdrc. 1 means write the alias definition to .vsdrc, 0 means do not write to .vsdrc.
For example, if you have a process that acts as a watchdog to kill misbehaving sessions, your code can programmatically update session stat 0 with the number of sessions killed. To view the statistics in VSD, you can add the alias ’NumSessionsKilled’ to SessionStat00.
Defining the following alias in .vsdrc:
setCtrAlias WatchDog SessionStat00 NumSessionsKilled counter64
none {The number of sessions killed} * 1
In VSD, when you load the statmonitor file or monitor, it will display the statistic name for the WatchDog process as:
SessionStat00 (NumSessionsKilled)
The Statistics Information window will provide the description.
Process name matching can includes a *, which will match any portion of a string or nothing. However, use the * with caution, since process names with or without a * are treated as unique patterns, and only the one that appears first will be used. Once a process name is matched to WatchDog, WatchDog*, or *, other potential matches to the process name are ignored, and the statistics will not be applied.
Managing aliases in VSD support files
VSD has two files that specify VSD settings such as window sizes, options, and aliases. These files are .vsdconfig and .vsdrc.
When VSD starts up, it looks for .vsdconfig. If this file does not exist, it creates a default one; if it does exist, all the settings will be used. VSD also looks for the file .vsdrc, and any settings in that file will override settings in .vsdconfig.
On shutdown, if Settings > Save Settings On Exit is true (set vsd(autoSaveConfig 0) ), then .vsdrc is written out based on the current settings in VSD; this include both ones that were read from file and any changes made while using VSD.
Note that these .vsdconfig and .vsdrc files are persistent and used by any version of VSD that you run; any version of VSD is intended to use any version’s .vsdconfig and .vsdrc. As of version 5.4, the location of these files can be configured (described here); previously all versions of VSD read from or created these files in the user’s home directory.
You may define statistics alias in either .vsdconfig or .vsdrc. If the alias is defined in .vsdconfig with writeToStartupFile as 0 (false) or if Save Settings On Exit is false, then the alias definition will not be written to .vsdrc, but will be read from .vsdconfig.
If you wish to add aliases to .vsdrc, either writeToStartupFile must be true, or Save Settings On Exit must be false, otherwise the definition will be lost after shutdown.
Alias templates for system operations statistics
The code that implements important GemStone operations such as reclaim and markForCollection collect a number of session statistics, to provide additional information for GemTalk Engineering analysis. These are undocumented, and many of them are obscure in the absence of source code. However, there are some that may be useful or suggestive when analyzing problems or performance issues.
VSD now includes an additional file, vsd.internal.stat.aliases.tcl, which contains aliases for the session statistics internally produced by GemStone operations. These are defined per GemStone version, and the statistics definition for each process in specific versions are provided, in addition to the alias names.
Note that since internal session statistics are not a supported or documented feature, there may be inaccuracies or version-specific differences that VSD does not detect.
- Reclaim and Admin Gem
- markForCollection
- fullBackup and restoreFromBackup
- page and object Audit
- cacheWarming
- logsender and logreceiver
Applying internal operation alias templates to application Gems
Aliases work by matching the pattern of the Gem name in the statmonitor data file. For example, the ReclaimGem has a name like GcReclaim6. Internal session statistics aliases are automatically applied to processes with names that follow this pattern.
However, processes such as markForCollection and restoreFromBackup are executed by ordinary Gems, which by default have the cache name GemN or Topaz. If you know the session that ran the given operation, you can apply the alias by name.
To do this, in the Main window, select the session, and use the right menu button pop up menu. Apply Alias Template For Type > provides a list of templates that you can select from to apply to the selected Gem process.
You may also set the cache name to exactly match the template definition, as listed in the submenu under Apply Alias Template For Type. For example, for an MFC session, execute:
System cacheName: ’MarkForCollection’.
And the MarkForCollection template will be automatically applied when the statmonitor file is loaded.
Removing Aliases
The Main Window process pane pop up menu item Remove Aliases is enabled if the process has an alias, either a custom alias from .vsdconfig or .vsdrc, or an applied system alias. Using the Remove Aliases removes either type of alias.
Removing custom aliases does not affect writing these alias to .vsdrc on shutdown; removes in this way are transient.
A system alias can be reapplied using the Apply Alias Template For Type menu. You cannot reapply custom alias; you will need to restart VSD to retrieve these aliases.
Existing undocumented statistics rename feature
VSD has had an existing but undocumented feature to rename statistics globally. This is done by including, in .vsdconfig or .vsdrc, lines similar to the following:
sl_stat -alias existingStatName newName
This causes all statistics named existingStatName to be replaced by newName whereever it is used. newName should not be an existing statistic name.
Bugs Fixed
VSD crash on Windows with command line argument of an invalid file
On Windows, if starting VSD with a command line argument and the argument did not specify a file in the current directory, VSD would crash.
VSD crash on negative time offset
When the Change Time Offset was set to a negative value, VSD would crash. (#46787)
Time offset applied when using relative timestamps
When using relative timestamps (Absolute Timestamps not enabled), Chart Windows labels are the time offset from the first record, which is 0. A time offset was inappropriately applied, making the charts difficult to read. (#46237)
Horizontal scroll bar in file drop-down obscured text
When multiple files are loaded, selection of a file is via a drop down near the top of the Main windows. If the filename was long, the horizontal scrollbar would obscure the text, making selection difficult. (#47660)
File load not responsive to interrupt
when loading a very large statmonitor file, and the interrupt button is pressed, it took an unreasonably long time for the load to be stopped. More callbacks have been added to improve responsiveness. (#44709)
File handling for lz4 files
Under some circumstances, the lz4 file handling code can attempt to close a file descriptor twice, which causes VSD to crash. One known case is when the a non-lz4-formatted file has an .lz4 extension. (#46249)
The errors that are reported when a file cannot be opened have also been improved.