com.gemstone.gbjstats

## Class GbjJmxCacheStatsMonitor

- java.lang.Object
- - com.gemstone.gbjstats.GbjJmxCacheStatsMonitor

-     public class GbjJmxCacheStatsMonitor
      extends java.lang.Object

  GbjJmxCacheStatsMonitor is a JMX-compatible application that can be used to monitor and control a GemStone system from a JMX-compatible monitoring tool, such as jconsole or VMware's Hyperic product.

  GbjJmxCacheStatsMonitor operates like statmonitor, gathering samples of the associated stone/cache's cache statistics at a regular sampling rate. But instead of writing them to a file, it instead organizes them as a collection of GbjJmxCacheStats (an extension of JMX's DynamicMBeans) that are accessible to JMX applications. In addition, it provides a way to execute short GS Smalltalk code snippets for performing basic system management tasks. To do so, it starts up an optional gem process (called the "control session" below) to execute the GS Smalltalk code.

  ## Executing GbjJmxCacheStatsMonitor

  Before starting GbjJmxCacheStatsMonitor, you must have properly registered the port you are planning to use. This is done by executing:

  unix> rmigistry <portNumber>

  To execute the GbjJmxCacheStatsMonitor, do the following:

  java -d64 com.gemstone.gbjstats.GbjJmxCacheStatsMonitor <portNumber> [args]

  where:

  " "
  portNumber: | A valid unused port on this machine
  | (Must have rmiregistry <portNumber> in effect)
  args:
  -h | -- print help text
  -s <stone> | -- Stone name
  | (defaults to gs64stone)
  -u <user> | -- GemStone user for control session
  | if not supplied, control session is not started
  | (User will be prompted for password)
  -g <gemnetid> | -- GemNetId
  | (defaults to gemnetobject)
  -i <interval> | -- Sampling interval in milliseconds
  | (defaults to 1000)

  In addition, GbjJmxCacheStatsMonitor can also be used in conjunction with the VMware Hyperic system monitoring tool. In this case, an additional argument must be added to the command line:

  java -d64 -Dinstallpath=<JDK directory> com.gemstone.gbjstats.GbjJmxCacheStatsMonitor...

  Where <JDK directory> is the directory containing the JDK installation on this machine.

  ## Data Layout

  Data from GbjJmxCacheStats will be presented in a layout determined by the underlying JMX object name format (refer to java JMX documentation for details). These use a pattern consistenting of a top-level domain name followed by a hierarchy of key/value pairs.

  There are two domains defined by GbjJmxCacheStatsMonitor:

  " "
  • | GemStone | for basic cache stat information for all GemStone processes, and
  • | Gemstone/Hyperic | for a more complex layout designed for access from VMware's Hyperic system monitoring tool.

  For the GemStone domain, the JMX registered object name format is:

  " "
  • | GemStone | (The Domain)
  • | stone | The name of the stone
  • | process | A particular GemStone process

  GemStone/Hyperic stats are available at two different levels: A summary "System" level and a "Process" level similar to the "GemStone" stats defined above. The format used for System-level GemStone/Hyperic stats is as follows:

  " "
  • | GemStone/Hyperic | (The Domain)
  • | version | The GemStone version of the stone being monitored
  • | stone | The name of the stone

  Process-level GemStone/Hyperic stats extend from the System-level format as follows:

  " "
  • | GemStone/Hyperic | (The Domain)
  • | version | The GemStone version of the stone being monitored
  • | stone | The name of the stone
  • | ptype | The type of GS process: stone, shpcmon, pgsvr, gem
  • | process | The GS process

  The actual System-level cache stats displayed are configurable by the user, using a template file that will be described later.

  By default, there are no Process-level GemStone/Hyperic stats displayed. These need to be manually activated by the user via the "enableHypericTracing" command (described below).

  Working with a JMX monitoring application, you can navigate through these hierarchies to find the GS process of interest. Once you reach this level, you can either display attributes or execute commands. In the jconsole tool, you can display attributes by selecting the "Attributes" tab in the tool.

  ## Executing Commands

  Once you navigate through the registration name hierarchy to either the System-level or Process-level statistics, you can find a list of commands to execute appropriate for that process/system. For the jconsole tool, these are available under the "Operations" tab.

  For Process-level statistics, there are three command available:

  " "
  • | stop | -- Stop the process using the GS Smalltalk stopSession command.
  • | kill | -- Kill the process using the OS-level "kill -9" command.
  • | enableHypericTrace | -- enable tracing of this process under the GemStone/Hyperic domain.

  For GemStone/Hyperic System-level statistics, the available commands are configurable by the user. By default, the following are available:

  - Shutdown
  - Gslist
  - FileSizeReport
  - CurrentSessions
  - CheckPointStatus
  - SessionsRefOldestCr
  - GcConfigReport
  - ReclaimGcGemReport
  - GcVoteState
  - Execute
  Most of these command execute the appropriate GS Smalltalk method with the same name on class System -- refer to the appropriate GS documentation for details on these commands. Shutdown will shutdown the stone and Gslist execute the OS-level gslist command. Execute can be used to execute any GS Smalltalk code entered as an argument into the command.

  ## Support Files

  As mentioned earlier, the user can configure the selection of System stats displayed or System-level commands available using 2 template files available under $GBJ/server:
  - GbjJmxSystemStatsTemplate.dat
  - GbjJmxCommandsTemplate.dat

  ### GbjJmxSystemStatsTemplate.dat

  After the header information (indicated by lines that start with "#"), the file contains a line for each statistic to be displayed, with 5 columns of information. Only the first column containing the name of the stat is used by GbjJmxCacheStatsMonitor -- the others are used by the GbjHypericPluginGenerator and deal with how Hyperic displays the information. Refer to Hyperic documentation for details.

  Any statistic from either the stone or the shared page cache monitor may be listed. GbjJmxCacheStatsMonitor will first check for a stat by that name in the stone, and if not found will then look for that stat in the shared page cache monitor.

  ### GbjJmxCommandsTemplate.dat

  After the header information (indicated by lines that start with "#"), the file contains clusters of 3 lines, which the 3 lines indicating:
  - The single-word short name to be used for the command
  - A longer sentence that describes the command
  - The GS Smalltalk code for the command
  GbjJmxCacheStatsMonitor only uses the first (single-word command name) and last (GS Smalltalk code) lines. The command description is only used in the Hyperic interface.
  Version:
    3.1.1

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `main(java.lang.String[] args)` Execute the GbjJmxCacheStatsMonitor program.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### main

          public static void main(java.lang.String[] args)

      Execute the GbjJmxCacheStatsMonitor program.
      Parameters:
        `args` - array of String containing arguments for progrem