1. VSD Overview

Next chapter

VSD (Visual Statistics Display) is a graphical tool that allows you to view and interpret the statistical information that can be generated by a running GemStone server or by GemBuilder for Smalltalk. GemStone utilities write this statistical data to a formatted file, and the VSD utility reads these files and displays the data graphically.

1.1 Statmonitor and VSD

Every commercial aircraft contains a flight data recorder, commonly called a black box. Black boxes are used to help determine what went wrong if the aircraft ever crashes. Without it, crash investigators would have very little to go on and the cause of many crashes would never be known.

In a production GemStone application, the statmonitor program serves the role of the black box. It runs in the background, logging the values of all cache statistics to a disk file. Should a problem with the repository occur, you can review these statistics to determine the cause, allowing you to identify problems and tune GemStone applications for better performance.

Data alone, however, is not enough; you need tools to display this data to allow analysis. VSD allows you to view and interpret the statistical information gathered by GemStone tools such as statmonitor. VSD reads the statmonitor files and displays the values in a graph. This graphical user interface gives you a meaningful way to see how your GemStone system changes over time, based on periodic samples of the system’s state.

Many questions about repository performance are impossible to answer after the fact unless statistics data files are available. For example:

Why did markForCollection take longer than normal?
Why did the backup run slower than before?
Why was there more repository growth than normal?
Which Gem session was consuming the most CPU or I/O during a time of poor performance?
Which Gem had the most number of commit failures?

If you’re trying to answer questions such as these, GemStone statistics are your best source of information.

While VSD is a standalone executable, it requires statmonitor or GBS Stat Monitor to generate data:

statmonitor is a stand-alone GemStone server executable with a command-line interface. This is provided as a utility with your GemStone server product and version, and is required to be the same product and version as the shared page cache it will be attached to. It does not log into GemStone nor use a GemStone session. Statmonitor writes data files to disk, in a platform- and version- independent format, in a text format.
GBS Stat Monitor is a GBS/VW process that can be enabled and disabled within a VW image. Like statmonitor, this writes data files to disk, in a platform- and version- independent format, as a binary .gfs file
VSD provides a graphical user interface for viewing the files that statmonitor or GBS produces. The VSD executable is provided for a variety of platforms.

Any version of VSD running on any platform can load statistical data files generated from any other platform and version of the GemStone server or GBS, although older versions of VSD may not be able to read statmonitor files produced by more recent GemStone server or GBS versions.

Statmonitor in the GemStone server

The statmonitor executable is provided as part of the GemStone/S 64 bit or 32-bit GemStone/S Server, and is described in the System Administration Guide for that version of the server.

Statmonitor requires a shared page cache, either the Stone’s shared page cache, if the stone is running on that machine, or a remote shared page cache; or, in some versions of GemStone, the -X option can be used to collect system statistics.

For example, to start statmonitor, at the command line, enter a command similar to:

statmonitor -f outputFile -i sampleInterval stoneOrCacheName

Statmonitor provides a large number of command line options to control monitoring, including the number and range of processes to monitor and how long to run. These options are provided in the System Administration Guide for your platform, or by executing statmonitor -h at the command line.

Statmonitor can be terminated by CTRL-C, or when a limit is reached as specified on the command line, and will shut down when the repository is shut down.

GemStone recommends running statmonitor at all times for production systems. If the GemStone system encounters an error, it may be able to report the nature of the error, but diagnosis of what led to that error often requires understanding previous activity and the actions of other processes, which can only be understood from statmonitor data. And some important questions, such as why you ran out of memory or why the repository is out of disk space, can only be analyzed using data from before the problem occurred.

Statmonitor statistics data files

Statmonitor writes text files to disk, either as plain text or in gzip compressed form.

These files contain formatted information, platform- and version- independent, that is read and displayed in VSD. VSD does not directly connect to processes in the GemStone server, but it can startup the statmonitor utility via the command line interface, and read the output files that are generated by statmonitor.

statmonitor data files may be generated as plain text or compressed using gzip; VSD can read plain text files and files zipped generated or zipped afterwards using gzip or lz4 compression.

The statmonitor data file format changes very rarely. The latest version of VSD can always read statmonitor files generated by older as well as recent versions of the GemStone server.

These files normally have the extension .out, .out.gz, or .out.lz4, although you may specify any file name.

File Size

For each sample, statmonitor writes a line for each process being monitored to a data file. This data file continues to grow as long as statmonitor is running.

With small intervals and a large number of processes, over time this file may become very large. A longer sampling interval will keep file sizes more reasonable, but may not be fine enough granularity to catch certain types of problems.

Writing the file in compressed format will save space.

Statmonitor includes options to regularly terminate the statmonitor file and begin a new one, either by time or by the number of samples collected. For example, you may wish to start a new file every 24 hours, and delete old files after a few days.

When you are diagnosing specific behaviors, a 1-second sample is the most convenient, although sub-second intervals may be needed. Monitoring running systems will usually require a longer interval to keep the file sizes manageable.

GBS Stat Monitor in GBS

GBS/VW can be configured to collect statistics describing the performance of its internal operations. These statistics are written to a file named GBSStatArchive-<dateAndTime>.gfs in the current VisualWorks working directory.

GBS main statistic types are for GbsSession and GbsSessionManager. GBS can also be configured to collect per-class cache inventories, in which each process line represents a Class that has instances in the classMap.

to start collecting both main and cache inventory statistics, in GBS execute:

GBSM statsEnabled: true

to start collecting only the main statistics, in GBS execute:

GBSM mainStatsEnabled: true

to start collecting only the cache inventory statistics, in GBS execute:

GBSM statMonitorRunning: true

To stop collecting statistics, use the same method with a false argument.

For more information, refer to the GBS User’s Guide chapter on profiling.

GBS statistics data files

Statistical data files written by GemBuilder for Smalltalk (GBS) are written in a binary form, with the extension .gfs, for GemTalk Flexible Statistics file.

1.2 Installing VSD

There is no need to run VSD on the same machine or on the same platform as the one on which the GemStone server or GBS is running. VSD on any machine and platform can read statistics generated on any other machine and platform. If you will be running VSD on a machine other than the one in which the GemStone server software is installed, you can download the appropriate platform of VSD and install it on that machine.

On UNIX platforms, VSD requires X-Windows.

Distribution

VSD is provided as part of the server distribution for all versions of GemStone/S and GemStone/S 64 Bit on all platforms.

You may also download VSD separately for any platform. VSD can read data files that are produced an any supported platform by any GemStone product, so you can analyze statistics on any VSD platform regardless of where the server is running.

VSD downloads for all platforms are provided on the GemTalk website, at http://gemtalksystems.com/vsd/

Installation on all platforms

If you are using VSD as part of your GemStone server distribution, VSD is already installed and ready to use.

Installation of standalone VSD is simple. The following instructions use / as a path separator, although the process is the same on Windows.

1. Download the VSD distribution, and unzip it into your VSD installation directory, vsdInstallDir.

This will create two subdirectories in vsdInstallDir; vsdInstallDir/bin, which contains the VSD executable files, and vsdInstallDir/lib, which contains several subdirectory trees containing the VSD library files.

2. It is convenient, but not required, to add vsdInstallDir/bin to the machine search path.

If the bin directory is not added to the machine search path, you may execute vsd directly from vsdInstallDir. VSD will search for the library files under the /lib subdirectory of the executable’s parent directory, so you do not need to add this directory to the path.