2. VSD’s Graphical Interface

Previous chapter

Next chapter

VSD provides a graphical way to view the data that is recorded by statmonitor. When you open VSD on this data, you will see a very large number of statistics that were recorded for potentially a very large number of GemStone processes. Not all of these are going to be useful; your task is to locate the interesting and useful information.

2.1  Starting VSD

You can start VSD from your windowing system or from the command line.

You may start VSD and automatically open a specific data file by:

For example:

prompt> vsd statmonDataFileName

vsdinstalldir/bin/vsd statmonDataFileName

The VSD Main window will appear.

2.2  Main VSD Window

When VSD is started, it displays the Main window. This window has a single instance and remains open while you are running VSD. When you are within VSD, the F12 key will bring the Main window to the top.

The Main window displays the list of processes and other information about the statmonitor file; here, you will locate and select processes and statistics for which you want to view charts.

This window also provides menus that allow you to set configuration options that control how your charts are displayed. The details for the various menu options are described in Section 2.9  .

Most of these display options are written to a .vsdrc file when VSD exists, which is read on startup. The next time you open VSD you will get the same options. Details of .vsdrc are here.

Loading data for viewing

If you opened VSD with a particular data file or files as an argument, the main window will display the processes listed from that file. Otherwise, you need to load a data file, or start monitoring a running server.

Loading an existing statmonitor file

To load a statmonitor file into VSD, use the menu item Main > Load Data File(s)...

This brings up a file dialog that allows you to browse for an existing statmonitor output file.

If you know the name of the file you would like to load, you can also type the full path in the File entry box.

Updating the view if the data file is updated

You may load a statmonitor data file that is still being updated by the live system. As new data is added to this file, you have the option to have vsd update its view.

If you select File > Auto Update, VSD automatically updates your display, and any associated charts, any time the data file changes. Otherwise, if auto update is disabled, you can choose File > Update periodically to update the displays when you choose.

Loading Multiple Files

You can load multiple statmonitor data files, either keeping the statistics separate by using the Main > Load Data File(s)... menu option, or appending them as if they were a single data set by using the Main > Append Data File(s)... menu option.

For more details on working with multiple files, see Working with Multiple Files.

Subsecond sample times

The statmonitor utility that is part of the GemStone server allows you to specify a sampling time in milliseconds rather than seconds, by using the -I option. Since versions of VSD earlier then v4.0 did not handle samples of less than one second, statmonitor historically did not write exact timestamps for subsecond sample rates; it treated the timestamp a counter that was incremented with each sample. The result was a series of timestamps that looked like 1-second intervals but represented statistic values at the requested sample increments.

GemStone/S 64 Bit version 3.3 and later, and GBS, write subsecond timestamps, adding milliseconds to the timestamp if needed. Earlier versions of GemStone, however, write relative timestamps for subsecond samples.

For statistics from older GemStone servers, there is no way to distinguish a true 1-second sample rate from a subsecond sample rate with nominal 1-second timestamps. When analyzing data with subsecond samples from earlier versions of the GemStone server, you must be aware of the sample rate when you load the file, and ensure you use relative timestamps and a time format of seconds.

Monitoring statistics on a running GemStone server

You can use VSD to start statmonitor and automatically read directly from the data file this statmonitor is writing to. This options is not available on Windows.

In order to monitor, you must have $GEMSTONE set to a GemStone server installation, and the machine search path set to include $GEMSTONE/bin, to allow VSD to provide a list of running GemStone caches to monitor. However, you can monitor any GemStone version or product, regardless of the version of GemStone specified in the environment of VSD. VSD uses the current GemStone environment only to list available caches. It reads information on the processes, and starts the correct version of statmonitor for the selected stone.

To monitor a live system:

Step 1. Bring up the Monitor window using the menu item Main > Monitor...

The Monitor window will display a list of all shared caches on this machine.

Step 2. Select the cache you wish to monitor, and the monitoring options.

These options are a subset of those offered by the server statmonitor utility. Options are:

  • The statmonitor output pathname.
  • The sample interval (in seconds)—that is, how frequently to statmonitor will read the cache to collect a sample.
  • The write interval—the maximum number of seconds to wait before flushing the samples to the output file. This determines the rate your monitoring view is updated.
  • Whether to compress the output file.
  • Any other statmonitor arguments you may wish to use; see statmonitor -h, or the System Administration Guide for the version of the GemStone server you are monitoring, for supported arguments.

Step 3. Click the Start button to start monitoring.

This will start statmonitor, and create a statmonitor data file in the specified location, or in the current working directory. If statmonitor startup fails, the Monitor status window will appear which shows the statmonitor command line with the error message.

The Monitor window will remain open. You can use the Dismiss button to close the window; this does not affect monitoring.

VSD loads the data file as soon as it has some samples in it (unless you have explicitly turned off Auto Update).

The statmonitor data file that is created by monitoring will grow as long as you are monitoring. If you have a large system and collect samples frequently, this file may become very large.

Step 4. Click the Stop button to stop monitoring.

If you have dismissed the Monitor window, you can re-open it using the menu item Main > Monitor. Select the cache you have been monitoring to enable the Stop button.

Note that the statistics data that is created will remain, and can be viewed later. It must be explicitly deleted if you no longer need it.

After you’ve loaded the data file or started monitoring, the VSD window looks something like this:

Process List

The upper list pane contains a list of all the entities—processes, thread-based sessions within processes, and other entities such as the disks—for which data is recorded in the statmonitor data. Depending on the options used to collect the data, this may include all GemStone processes or a small subset, and may include a number of non-GemStone entities including the operating system, disks, etc. While these are not all strictly “processes”, in the following discussion this term is used to include all entities that appear in the process list.

For each process, session, or other entity, the display includes:

  • The StartTime - the time that process first recorded a sample, adjusted to local time on the machine executing VSD.
  • The EndTime - the time that process last recorded a sample, also adjusted to local time.
  • The File id for the file in which it was recorded. This is of interest if you have more than one file loaded; the file id corresponds to the number in the file select drop-down.
  • The total number of Samples for that process recorded in the data file.

If you are monitoring, processes that are currently running and for which samples are being taken are shown in green, and these number will change as new data samples are taken.

  • the OS ProcessID for the process. Multi-threaded processes in which the threads are GemStone sessions will have individual entries for each thread, and list the same process Id for each.
  • the GemStone SessionId for that processes. This only applies for GemStone sessions.
  • the process Type.

GemStone processes fall into a number of types, which govern which statistics apply. The common process types are:

Stn — Stone (and Page Manager in cases where this is a thread in the Stone )

Shrpc — Shared page cache monitor

Pgsvr — AIO or free frame page server, or a page server for a remote session

Gem — Gem; includes system Gems, RPC Gems, and linked sessions such as linked Topaz

Statmon — statmonitor

Additional types will appear if you are also monitoring OS information, including platform-specific statistics.

  • the process Name.

This is assigned by statmonitor or GBS’s Stat Monitor, and displayed in VSD. It may be assigned for Gem processes within the GemStone server; see Process names in GemStone.

To reduce the number of processes that are visible in the list, the processes of a given type can be hidden, using the menu item Hide Instance By Type....

Sorting

By selecting a column header in the main windows, you can sort all the processes by that column’s attribute. The current sort column is indicated by an up or down arrow next to the column label.

Within primary sort order, the results are further sorted by a secondary sort attribute. This is indicated by the column label in italic font. To specify the secondary sort attribute, right click on the column label.

Note that the secondary sort key direction (ascending or descending) is always the same as the direction of the primary sort.

For example, if you want to find the Stone, you can sort by Type, descending, which sorts the type Stn first. Or, if you know the session ID of the Gem, you can sort by SessionId and scroll until you find that Gem.

Selecting Process

When you select a process, the list of statistics relevant for that process is displayed in the statistics pane. Multiple selection is allowed.

Searching for Processes

You may search for a process by name or type, using the Process List pane popup menu item Search..., control-S, or control-F when focus is on the Process List pane. This opens a search line just above the Process List pane.

Selecting Sets of Processes

The menu option Main > Select Instances By..., also available on the process list popup menu, allows you to select all processes matching a particular criteria. The options are:

All —select all processes.

Clear —deselect all processes.

Name... —open a dialog allowing you to enter a string, select processes matching that name. The string supports wild cards * and ?, and allows you to search case-sensitive or case-insensitive.

Process ID... —open a dialog allowing you to enter a process Id, and select processes with that process Id.

Session ID... —open a dialog allowing you to enter a session Id, and select processes with that Session Id.

Statistic—select all processes for which the currently selected statistic or statistics apply. Does nothing if no statistic is selected.

Type —select all processes of the same type as the currently selected process or processes. Does nothing if no process is selected.

Statistics List

The lower pane displays a list of statistics.

Each process type has a specific set of statistics that are relevant for that process. Many of these are unique for that process type; for example, CommitCount applies to Gem processes, while TotalCommits is meaningful for the Stone. Others, such as UserTime, apply to all processes.

When no process is selected, all statistics in the system are shown. When a particular process is selected, only statistics appropriate for that process type are listed. When multiple processes are selected, only statistics that are common to all the selected process types will be listed.

You may scroll down the list to locate the statistic you want. Typing in the first character will select the first statistic with a name beginning with that letter.

Notice that some statistics are listed in bold font, while others are in regular font. Statistics with the font in bold have non-zero values recorded.

Searching for Statistics

You may search for a statistic by entering the first characters in the Statistic name, or by using the Statistic list popup menu item Search for Counter..., control-S, or control-F when focus is on the Statistics List Pane. These open a search line just above the Statistics List Pane.

Controlling visibility of statistics

Hiding statistics with only values of zero

You may hide statistics for which the value of that statistic is 0 for the entire sample set. These are the statistics that are listed in non-bold font.

To hide statistics where there are no non-zero values, check No Flatlines in the Main menu or in the right mouse button popup menu. Note that "No Flatlines" means "No Flatlines at zero", and does not apply to statistics whose values present a flat line at a non-zero value.

Meaning of statistics

While many statistics have intuitive names, you will often need to look up details. You should not expect to understand every statistic recorded for your system. Some of these statistics require an intimate knowledge of GemStone server internals, some are experimental, and some may only apply under specific server conditions. GemStone documentation, Techtips, and analysis from GemStone Technical Support will include specific statistics that are particularly helpful.

The information in the current version of VSD, including more detail, is displayed in the Statistics Information Window. To open the Statistic Information, use the menu item Main > Show Statistics Info.

This singleton window can be left open; it will display the details for any selected statistics as it is selected. You can also lookup statistics using the drop down.

Selecting and viewing statistics

After you have selected one or more processes and one or more statistics, you can display these results in a new Chart Window by clicking on the New Chart button. You can create a named chart by entering a name in the Chart name entry field.

If you have a chart open, you can add the selected statistics to an existing chart. Select the chart by name in the drop-down with the Chart name entry field, then click on the Add Line button. The Chart name is set to the most recently selected chart, so if you do not explicitly select a chart, the statistics will be displayed in the most recently selected chart.

The following shows the main window with one process selected, the Stone, and two statistics selected, TotalAborts and TotalCommits.

2.3  VSD Statistics Chart

To view data for particular statistics, you will open a Chart Window. These VSD statistics charts allow you to view and analyze the data for the statistics you have selected. You may have many Chart Windows open.

There are a variety of ways to control the display and to perform operations on selected lines. The details for the various menu options are described under Section 2.9  .

Chart Window

When you first open a chart, all the values for all statistics are displayed with its default settings. Each line has a unique color and/or pattern.

At the bottom is the Legend - the list of process statistics that are viewed in this chart. Each is described by Process name and statistics name.

The axis of the graph are labeled; the horizontal axis is always time.

The vertical axis is labeled with the number of the units for all the statistics; this may or may not be meaningful, if the statistics used different units of measurement. For example, comparing the counts of the number of commits and the time waiting for I/O, by units, does not directly make sense. However, it can be very useful to see how each varies relative to the other over time.

Chart Options

You can customize and manipulate a VSD chart in many ways to make your analysis easier. A few of the more useful are described here.

Zoom

To zoom in on a subsection of the chart, use the menu item Chart > Zoom In. This prompts for a rectangle to zoom in to, allowing you to view with more detail the section of the chart that you are interested in. You can zoom in multiple times to narrow your view further.

Zoom Out returns you to the previous level of zoom.

Time Format

The times marked on the horizontal axis, by default are in HH:MM:SS format (with hours in 24-hour format). If your sample spans multiple days, you can set the time format to include the month and day using the Chart > Time Format menu item.

Selecting a Line

You can select an individual line from the Legend at the bottom, or by clicking on that line in the graph. Selecting a line colors it red and displays information about that line.

When a line is selected, the following information is available:

  • On the graph itself, a brief summary statistics for the line. This includes the number of data points for that statistic, the minimum, maximum, and standard deviation are displayed. These units stay the same regardless of scale or transformation.
  • When the mouse is over a data point in the graph, the X (time) and Y (units) of that point are displayed. These units stay the same regardless of scale or transformation.
  • the name of the statistic.
  • the current filter. The filter allows you to distinguish absolute values from rates of change. Each statistic has a default filter based on its type, which can be changed as needed.
  • The scale or other transformation. The scale allows you to compare lines with widely different ranges of values, by scaling one or the other to bring the ranges closer together.

Copying value from a line

When you have a selected line, you can copy the value of a point on the line using the Chart windows pop-up menu item Copy Y value. This menu item is only displayed when you right click while the cursor is over a point on the active line.

The copied value can be pasted into another application using control-V. Middle-button paste depends on the target application copy buffer and may or may not work.

Saving a graphic of the chart

Using the Chart Window menu item Chart > Snapshot, you can save a .gif image of the graphics on the Chart Window to a disk file for later reference.

Changing Line Options

Filters

The filter allows you to view either absolute values, rates of change per second or sample. Filter options are:

No Filter — Displays the values for the statistic exactly as they are expressed in the statmonitor text file.

PerSample — Displays the difference between two consecutive samples of the statistic.

PerSecond — Displays the difference between two consecutive samples of the statistic, divided by the number of elapsed seconds between the two samples.

Aggregate — Displays a running total for the per-sample deltas of the statistic.

These filters can be adjusted for an individual line using the filter drop-down on the menu bar, , or for all lines on a chart using the menu items under the menu All Lines.

Scaling

When you have multiple lines with widely different ranges of values, you can increase the visibility of a line relative to the other line by scaling it.

Select the line, and in the upper right, use the arrow indicators to scale up or down the line.

Using the Line > Compute Scale or the Chart > Compute Scale All menu options will calculate and apply a scale based on the chart data values.

Other Transformations

By default, S is selected for the transformation setting, between the filter list and the scaling value entry field. When S is selected, the numeric scrolling field is used to scale the selected line.

You may also select other options, rather than S. This allows you to transform the line by adding, subtracting, multiplying, or by dividing the value in the numeric scrolling field.

Summary of Information on a line

The menu item Line > Log Info will open (or append to an already open log window), summary information about a single line. For example:

Summary of Information on a section of line

A very useful tool is collecting statistics on a section of line. For example, you may want to know the commit rate over a single period of intense activity, rather than for the entire period of sampling, or the rate of growth of a CommitRecordCount.

The menu item Line > Log Delta will allow you to select two point on the selected line. It then opens (or appends to an already open log window), summary information about that section of line.

The useful information will be different for counter statistics vs. values. For CommitCount, which is a counter type and therefore already a delta, the average will be of interest; for values is as CommitRecordCount that provide unit values, the value delta will be useful.For more on statistics types, see the descriptions here.

Other ways to control the view

There are many ways to control what you are viewing to make analysis of your data easier. Here are a few that are particularly useful.

Combining statistics values for multiple processes

Normally, when opening a chart or adding lines to an existing chart, one line is added for each selected process for each selected statistic. If you have selected a large number of processes — for example, all Gems — this may be cumbersome to see in the resulting chart.

In cases like this, you can combine values for a single statistic for all the selected processes. To combine values, in the Main VSD Window, check the value Combine in the Main menu or in the right mouse button popup menu.

Graphing against scales on both right and left side Y-axis

By default, all lines in a graph are plotted according to Y-axis units scaled on the left-hand side of the chart. You can instead plot some of the lines according to units scaled on the right-hand side of the chart, which will allow them to use a different scale. This is useful when the lines use different units of measurement from those plotted on the left.

To change the side on which a line is selected, with the line selected in a Chart Window, uncheck the value Graph on left axis on the Line menu.

Rolling Left Trim

When monitoring a running GemStone server, over a long period of time there may be many samples recorded, so that the most recent samples are in a very narrow section of the graph along the right side.

Since in many cases the most recent statistics are of particular interest, you can configure the display to only show the samples for a fixed period of time before the latest loaded sample; as new samples are loaded, the older ones are no longer displayed.

The File menu item Set Rolling Time Window... , or Cntrl-shift-R, brings up the following dialog:

Rolling left trim, like auto update, applies to the current file, which 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 Rolling Left Trim Window.

Process names in GemStone

When statmonitor records statistics for Gem processes, it records them with the name “Gem”, or for linked topaz logins, “Topaz”. This can be modified to an application-meaningful name in the GemStone server, so this name is recorded in the statmonitor data. This can be particularly useful for regular maintenance processes, such as your backup or markForCollection, that are run from scripts.

The options to set the process name vary by the GemStone server version.

  • The topaz command line -u argument name is used to set the process cache name, in GemStone/S 64 Bit v3.4 and later.
  • Before logging in, the command:
topaz> set cachename MyProcessName

can be executed to set the cache name. This is available for linked sessions in v2.4 and later, and additionally for RPC sessions in v3.4 and later.

  • After login, in the session you want to rename, execute:
System cacheName: 'myName'

Depending on how soon you can execute this after login and the statmonitor sample rate, you may have one or more samples showing the original default name.

Changing Hours Offset

Statmonitor data files include a header file that specifies the timezone in which statmonitor recorded this file. VSD automatically adjust the timestamps displayed according to this timezone, rather than the timezone of the node actually running VSD. This allows you to correlate VSD with log file messages, regardless of the timezone in which VSD is running.

Depending on your configuration, this may not always be what you want to see. You can manually adjust the display offset using the main menu option Change Time Offset..., and select the number of hours plus or minus to adjust VSD’s display:

Commas in Numbers

To make it easier to read very large numbers, by default VSD displays comma separators, e.g. 6,000,000. VSD does not have localization; if the separators are distracting, you can disable them using the Main menu item Preferences > Show Comma In Numbers.

2.4  Using and Creating Templates

VSD templates let you quickly create a chart with a commonly used set of statistics. Templates are helpful if you find yourself performing the same task frequently in VSD — for example, monitoring the same five or six statistics. By creating a template for the statistics that you want to monitor most frequently, you can automate the task of building charts.

VSD is shipped with a set of predefined templates. You can open charts on these templates using Template > New Template Chart, and choosing any of the predefined templates. If you create your own custom templates, they will also appear in this list.

You can create a custom template based on a chart you have created in VSD, or by editing the formatted text file that contains the templates. See VSD Configuration Files for more on the text file and how it is formatted, and editing this file outside of the GUI.

To create a custom template from VSD:

Step 1. set up a chart with the processes, statistics, scaling, and so on, that you want in your template.

Step 2. Chose the Chart menu item Save Template. This will prompt you to enter a name for the custom template. Hit the enter key when you are done.

You can now use your new template, from the Template > New Template Chart menu item.

if you want to remove your template, edit the .vsdtemplates file, and use the menu item Chart > Reload Template File to reload the templates file.

Gem and Pageserver Names in Templates

When you create a template that includes processes that are Gems or PageServers, the name of the process, as well as the type, is included in the template. This helps avoid an excessive number of lines appearing when the chart is opened.

The name that is included does not include any serial numbers that are displayed with the name in VSD. So for example, if the chart on which you are creating a template includes a Gem named Topaz19, the template will use Topaz* as the name. When you later use the template to create a chart, lines will be added for all Gems with the name Topaz.

Since you may have many Topaz processes, and cannot determine which one is performing a particular task such as backup or MFC, including Gem and Page server statistics in templates requires more consideration. Providing the Gem with a name, as described under Process names in GemStone, is one solution.

2.5  Working with Multiple Files

VSD provides a number of ways to work with multiple statmonitor data files. While analysis is often done using a single statmonitor data file or monitoring session, there are a number of cases in which you need to work with multiple files. For example:

Production systems should normally run statmonitor at all times, and archive the results for some period of time, to ensure that this information is available for diagnosis if a problem occurs. This usually involves automatically restarting statmonitor periodically, for example, starting a new data file every day at midnight.

When studying the progress of a operation such as a markForCollection, the statistics of interest may span more than one data file.

If you have statistics for remote caches, you may wish to display these along with the statistics for the Stone’s cache to track the interactions.

For example, if you are studying the effect of a configuration or code change on performance, you may have data sets for two runs of a particular operation, and want to compare them to understand the differences.

Loading multiple data files

Loading multiple Individual data sets

You can load multiple statmonitor files using the menu item Main > Load Data File(s)...., or by specifying multiple files on the command line.

Loading multiple files as a single data set

If your multiple data files are logically a single data set (for example, you start statmonitor on the same repository, shut statmonitor down, and start statmonitor again), then you can append the second and later data files to the first file, allowing you to see all the processes and samples at once.

To open multiple files so they are appended, use the menu item Main > Append Data File(s), or the -a command line argument. The File list displays the name of the first file, with [Appended] following.

You must ensure that the files to be appended are specified in the correct order. The append operation does not detect and prevent loading data sets that are in incorrect order or overlap, and loading invalid sequences results in unpredictable behavior and possible errors.

Current File and the file mode

VSD always has a current file, which is displayed in the File: list. Operations on the File menu apply to the current file. If you have multiple files loaded, you can use the File: drop down to change the current file.

Each loaded file has an sequence number, in the order in which they are loaded; this number is displayed in the File: field and drop-down list and in the File column in the process list.

In Single File mode, the current file is the only file that is displayed. In Multiple File mode, all files are displayed. This is toggled using the Main menu item Single File Mode.

In multiple file mode, you can see which file is associated with a given process in the File column. The following example shows three sequential sample sets on the same stone and topaz process.

Chart with Statistics from Multiple Files

When you ave multiple files loaded separately, the legend in the Chart Windows indicates which file the statistics values originated with by appending a [N] to the statistic name for each file, except File 1. The N corresponds to the File list index sequence number of that file, no number indicates it is from file 1.

Comparing statistics for multiple sequential runs

If you are testing the impact of changes in code or configuration values, you may have multiple sets of statmonitor data that represent similar operations, that are offset in time. You can view these data sets overlaid by using relative time stamps, so each data set is charted with the same starting point.

The following chart includes the CommitCount for the Topaz process in each of the three files. Since Absolute Time stamps is unchecked, they all are displayed as if the starting time was the same.

Note the index following the process name in the legend that indicates which file each line is based on.

2.6  Monitoring

VSD can be used for ongoing monitoring of a active production system, allowing an administrator to see potential problems and correct them before they affect performance.

Monitoring a system, using Main > Monitor..., is described under Monitoring statistics on a running GemStone server. However, since production systems should be running statmonitor in any case, it is more efficient to use VSD to read the production statmonitor data files as they are being written.

Auto update

Using the menu item File > Auto Update when or after loading a file will tell VSD to load new records in the statmonitor data file as they are written.

See only the most recent statistics

Monitoring is not concerned with a view of system behavior over time; the most recent statistics are all that are relevant. Using the Rolling Left Trim feature, only the most recent statistics are displayed. For more on this features, see Rolling Left Trim.

Auto Append of newly created files

To make statmonitor data files easier to manage, most production systems will automatically start writing to new statmonitor files periodically. There are a number of statmonitor features that support this, such as -r, -R, and -k.

The File > Auto Append Next File will open any new statmonitor files that appear in the same directory as the original statmonitor file, and append these statistics to the current view. This allows monitoring to continue seamlessly when statmonitor data files roll over.

Note that this feature cannot detect if the files are from the same sequence of statmonitor data files, or from an unrelated system or series. It is not recommended to mix statmonitor files from different sequences in the same directory.

Font colors indicating live processes

While a statmonitor data file is being updated on disk, and VSD is automatically updating its view based on the disk file, the font of the "Samples" number for that process will be shown in green font.

When that process is no longer having samples recorded, either because the file is no longer being updated or that particular process exited, after a timeout the Samples count will be shown in regular black font. This allows you to detect if a process has exited unexpectedly or if something has gone wrong with the monitoring itself.

The timeout by default is 90 seconds. If the statmonitor interval is similar or larger than this, the process may be marked as inactive although it is functioning as expected. You can adjust the timeout using Main > Settings > Change Inactive File Timeout.

2.7  Aliases for statistic names

When GemStone software generates statmonitor data, each statistic is recorded with a meaningful name, such as "CommitCount". GemStone also provides application-defined statistics, which have non-meaningful names: for Gems, SessionStat00... SessionStat47, and for the Stone, GlobalStat00..GlobalStat47. These can be programmatically updated by customer applications to track application-specific information, and may be used differently by different application processes.

Some GemStone processes, such as markForCollection, reclaim, and backup, use Session statistics to track internal progress. While this is designed for GemStone Engineering analysis, this may be helpful in understanding your system.

Since analysis is easier with meaningful names, there are several kinds ways to manage aliases in VSD:

Global aliases

Statistics can be globally renamed in VSD, by including a directive:

sl_stat -alias existingStatName newName

in .vsdconfig or .vsdrc. This causes all statistics named existingStatName to be replaced by newName whereever it is used. newName should not be an existing statistic name.

Process-specific alias names

VSD custom aliases allow you to associate a name, description, and other details that VSD uses for display, with an existing statistic name. This association is set by the name of the process (and, optionally, by GemStone version).

This is designed in particular to define meanings for SessionStat00.. SessionStat47. However, aliases can ba applied to any Gem statistic.

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]]

where the arguments are:

CacheNamePattern - cache name of processes to match, case sensitive

StatName - name of an existing cache statistic

Alias - name of the alias

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

You may set aliases in either .vsdconfig or .vsdrc. If you may run older versions of VSD on this node that will access the same .vsdconfig and.vsdrc, you should ensure that the definitions are conditionalized:

if {[llength [namespace which setCtrAlias]]} { 
definitions of aliases
}

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 next time VSD is shut down.

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.

The VSD distribution includes 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.

Version 3.2 and later:

  • Reclaim and Admin Gem
  • markForCollection
  • fullBackup and restoreFromBackup
  • page and object Audit
  • cacheWarming
  • logsender and logreceiver

Version 2.4.x:

  • PageManager
  • Reclaim and Admin Gem
  • markForCollection and Fast FDC
  • cacheWarming

32-Bit GemStone/S:

  • PageManager
  • GcGems, Reclaim and Epoch
  • markForCollection

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 named sessions.

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

2.8  Setting Background Color

When running multiple instances of VSD, it can be helpful to be able to distinguish the VSD charts belonging to different instances. To support this, you may set the background color of the VSD instance. Once selected, all VSD windows for that VSD instance will display this color in all windows and charts.

Setting a master background color changes the window background, which ordinarily is a light gray, and also changes the background color for process lists, fields, and graphs which ordinarily have a white background.

The color may be set in a number of ways:

On UNIX platforms:

On Windows:

TK color names and RGB values are provided here:

http://www.tcl.tk/man/tcl8.6/TkCmd/colors.htm

TK provides over 750 color names describing over 500 unique colors.

After setting a background color, for example:

Note that the background color is not saved to the .vsdrc file, since it is intended as a way to distinguish different instances of VSD on the same machine, rather than as a configured color for VSD in general.

2.9  Menu Options

This section describes the menu items available on the Main and Chart Windows in VSD.

Main Window Main Menu

Load Data File(s)...

Load one or more data files. Each file is loaded independently.

Append Data File(s)...

Load one or more data files. If more than one file is selected, merge the data in all files into the current file if a file is already loaded, or into the first file in the list. For correct operation, the files must represent sequences in the same repository and be loaded in sequence.

Monitor...

Open a dialog to display the process and statistics for a running stone. This invokes statmonitor with the selected options, and reads the resulting file with automatic updates. Not available on Windows.

Change Directory...

Change the current VSD directory. This is useful when monitoring, to set the directory in which the statistics file will be written.

Change Time Offset...

Set the offset between the current system time zone and the time zone of the data file.

Set Master Background Color...

Open a dialog to set the background window color.

Copy Selection

Copy the selected processes and statistics to the VSD clipboard.

Show Statistics Info

Open the Statistics Information Window

Select Instances By...

Allows you to:

  • All selects all processes.
  • Clear unselects all selected processes
  • Name... opens a dialog to let you enter a string, and selects all process with names that match. Supports wild cards * and ?, and case-sensitive or insensitive.
  • Process ID... opens a dialog to let you enter a process id, and selects all process with that process Id.
  • Session ID... opens a dialog to let you enter a session id, and selects all process with that session Id.
  • Statistic selects all processes that define the currently selected statistic or statistics.
  • Type selects all processes that are the same type as the currently selected process or processes.

Hide Instances by Type...

Allows you to hide specific process types in the Process list.

Combine

When selecting multiple processes, combine the statistics data for all selected process into a single line.

No Flatlines

Exclude statistics that do not change.

Single File Mode

When this is checked, the display includes only the currently selected file. When not checked, the statistics for all open files are displayed together.

Absolute Timestamps

If checked, timestamps are in real time; if not checked, timestamps are relative to the beginning of the data file.

Copy Referenced Lines

In a chart window, when performing line arithmetic, make copies of the lines rather than using the lines values directly.

Settings

Allows you to set or unset the display options:

  • Change Inactive File Timeout sets the period of time that VSD waits before determining that no new samples will be added to a given statistic and changing the font color to inactive.
  • Choose Fonts... contains submenu items that open a Font Dialog, allowing you to select fonts for the Main Window, Charts, Chart Data Logs, and Help Text.
  • Confirm Exit determines if VSD will prompt you before exiting.
  • Save Settings On Exit determines if VSD will write the current settings to .vsdrc on exit.
  • Show Commas In Numbers allows you to see numeric values over 9999 with a comma.

Save Settings

Save the current configuration to .vsdrc. This is useful when Save Settings On Exit is false.

Exit

Exit VSD.

Main Window File Menu

Info...

Open a dialog providing information about the current file.

Update

Check for additional data samples in the current disk file, and update the display with changes.

Update All

Check for additional data samples in the disk files for all open statistics file, and update the display with changes.

Auto Update

When this is checked, the system will automatically check for additional data samples in the current disk file, and update the display with added entries.

Auto Append Next File

When this is checked, the system will automatically check for new files in the same directory as the original file (regardless of the name, and automatically open and append these samples to the existing view. Checking this option also checks the Auto Update item. This option is not available on Windows.

Enabled

Used when in multiple file mode (that is, Main > Single File Mode is not checked); the statistics for this file will not be displayed.

Untrim Left

Remove left trims in all charts.

Untrim Right

Remove right trims in all charts.

Set Rolling Time Window...

Brings up a dialog to allow you to set a time period. When monitoring a live system, a chart will only show the values collected up to the give time period before the current moment.

Main Window Chart Menu

Add to Chart

Add the currently selected process statistics to the most recently selected chart.

New Chart...

Open a new chart with the currently selected process statistics.

Show Legend

Set the default for displaying the legend with the process and statistic name for the various lines at the bottom of the chart window.

Time Format

Set the default time format. Options are Seconds, Hour:Minute:Second (the default), or Month/Day Hour:Minute:Second. Note that if Main > Absolute Timestamps is not checked, all formats are in relative to the first sample in the file.

Default Line Style

Set the line style; options are linear (the default), step, natural, and quadratic.

Show Time Axis Title

Display the label on the horizontal axis, generally the name of the data file

Show Left Axis Title

For statistics graphed on the left axis, display the label on the left side vertical axis, the name of the units for the selected statistic.

Show Right Axis Title

For statistics graphed on the right axis, display the label on the right side vertical axis, the name of the units for the selected statistic.

Show Current Values

Include, on the menu bar, display areas for the X and Y values of the point under the cursor on the selected statistic.

Show Min and Max

Include, on the menu bar, display areas for the maximum and minimum values of the selected statistic

Show Line Stats

Display a line indicating the number of points, minimum, maximum, mean, and standard deviation for the selected statistic, in the upper left of the graph area.

Show CrossHairs

display cross hairs centered on the cursor location.

Show Grid Lines

display grid lines.

Selected Line Color...

Set the color to be used for the currently selected line in all charts.

Close All Charts

Close all open chart windows.

Main Window Template Menu

Reload Template File

Reread the template file from disk.

New Template Chart >

Select from the templates and open a new chart using that template

Templates Use Selection

If selected, for templates that have patterns using *, open templates using only the selected processes.

Main Window Help Menu

How to...

Open Help with list of how-to topics.

Main Window...

Open Help for the Main window.

Chart Window...

Open Help for the Chart window.

All Topics...

Open Help with list of all topics.

All Help Text...

Open Help with all help in a single window.

About VSD...

Open About VSD dialog.

Process List Pane Pop-up Menu

Search...

Search for a process using name or part of a name.

Apply Alias Template For Type

Allows you to apply a predefined set of aliases to a process that is performing a specific GemStone function, such as markForCollection, in order to view session stats associated with that function.

Remove Alias

Removes an applied alias template from the selected process.

Hide Instances by Type...

Allows you to hide specific process types in the Process list.

Select Instances By:

Allows you to:

  • All selects all processes.
  • Clear unselects all selected processes
  • Name... opens a dialog to let you enter a string, and selects all process with names that match. Supports wild cards * and ?, and case-sensitive or insensitive.
  • Process ID... opens a dialog to let you enter a process id, and selects all process with that process Id.
  • Session ID... opens a dialog to let you enter a session id, and selects all process with that session Id.
  • Statistic selects all processes that define the currently selected statistic or statistics.
  • Type selects all processes that are the same type as the currently selected process or processes.

Combine

When selecting multiple processes, combine the statistics data for all selected process into a single line.

No Flatlines

Exclude statistics that do not change.

Single File Mode

When this is checked, the display includes only the currently selected file. When not checked, the statistics for all open files are displayed together.

Absolute Timestamps

If checked, timestamps are in real time; if not checked, timestamps are relative to the beginning of the data file.

Chart Window Chart Menu

Add from Template

Open the list of templates and add the process statistics specified by selected template to the current window.

Save Template

Create a new template from the current set of processes and statistics. The prompt for the name is in the menu bar area. Note that the resulting template may need further editing if Gem processes are selected.

Paste

Paste a line that was previously put into the VSD clipboard, and clear the clipboard.

Snapshot

Make a .gif of the chart, and allow you to select a directory and name for the resulting file.

Help...

Open Help for the chart window

Zoom In

Select a rectangle and make this the new graph display area.

Zoom Out

Undo the most recent zoom.

Compute Scale All

Compute a scale for every line in the chart.

Unscale All

Remove any scaling done to any lines.

Show Legend

Display the legend showing the process and statistic names for the various lines at the bottom of the chart window.

Time Format

Set the time format. Options are Seconds, Hour:Minute:Second (the default), or Month/Day Hour:Minute:Second.

If Main > Absolute Timestamps is checked, Seconds provides the GemStone timestamp value; other values provide the sample’s time, adjusted by a value set by the Main windows’ Change Time Offset.

If Main > Absolute Timestamps is not checked, the display is either in seconds since the beginning of the file, or nnhnnmnns, or nndnnhnnmnns since the beginning of the file.

Show Time Axis Title

Display the label on the horizontal axis, generally the name of the data file

Show Left Axis Title

For statistics graphed on the left axis, display the label on the left side vertical axis, the name of the units for the selected statistic.

Show Right Axis Title

For statistics graphed on the right axis, display the label on the right side vertical axis, the name of the units for the selected statistic.

Show Current Values

Include, on the menu bar, display areas for the X and Y values of the point under the cursor on the selected statistic.

Show Min and Max

Include, on the menu bar, display areas for the maximum and minimum values of the selected statistic

Show Line Stats

Display a line indicating the number of points, minimum, maximum, mean, and standard deviation for the selected statistic, in the upper left of the graph area.

Show CrossHairs

display cross hairs centered on the cursor location.

Show Grid Lines

display grid lines.

Close

Close this chart window.

Chart Window Line Menu

Log Info

Add information on the currently selected statistic or statistics to the log window.

Log Delta

Allows you to select a start and end point on any lines, and adds information on the delta between these two points to the log window.

Compute Scale

Compute a scale for this line.

Unscale

Remove any scale on this line.

Graph on Left Axis

When selected, the line is graphed against the axis on the left side of the chart; if unselected, graph against the axis on the right side.

Symbol

Set the symbol to use to indicate points on the line; options are none (the default), scross, splus, square, triangle, circle, diamond, plus, or cross.

Style

Set the line style; options are linear (the default), step, natural, and quadratic.

Update

Reread the data file associated with this line for new entries.

Add Lines

Add the next line selected to the selected line.

Diff Lines

Subtract the next line selected to the selected line.

Divide Lines

Divide the next line selected by the selected line.

Change Integer Type

Allows you to convert the interpretation of a 32-bit statistic to 64-bit.

Normalize

If this item is checked then the line will be normalized. Cannot be used with a line offset.

Trim Left

Allows you to select a point on the selected line, everything to the left of this point (earlier) will be hidden.

Trim Right

Allows you to select a point on the selected line, everything to the right of this point (later) will be hidden.

Untrim Left

Undo any left trims done to this chart.

Untrim Right

Undo any right trims done to this chart.

Copy

Copy the selected line (process and statistic) to the VSD clipboard.

Cut

Remove the selected line, and add it to the VSD clipboard.

Delete

Remove the selected line.

Chart Window All Lines Menu

No Filter

Remove any filter from all lines on the chart; display the values exactly as they are in the statmonitor text file.

PerSample

Apply the per-sample filter for all lines on the chart; displays the difference between two consecutive samples of the statistic.

PerSecond

Apply the per-second filter for all lines on the chart; displays the difference between two consecutive samples of the statistic, divided by the number of elapsed seconds between the samples.

Aggregate

Apply the aggregate filter for all lines on the chart; displays a running total for the per-sample deltas of the statistic.

 

 

Previous chapter

Next chapter