Oracle Coherence Monitor User Guide

Oracle Coherence Monitor

User Guide

Database Configuration
The OC Monitor requires a database that provides tables for the following information:

Alert Thresholds
Each OC Monitor instance requires a database table that contains alert thresholds and enable/disable flags. The values in this table are used by the alert engine at runtime. If this table is not available, alerts will not function.
Historical Data
If you use the OC Monitor Historian, it requires database tables in which to write data.

The following recommendations are for installations where the HSQLDB database included with RTView is replaced with another database accessible via JDBC or ODBC. Note that while the HSQLDB database may be sufficient for evaluation and testing, it is not recommended for use in production deployments.

When using HSQLDB, the database capacity and space requirements described below should be applied to RAM for the system hosting HSQLDB because its tables are held in memory, not on disk.

The default Coherence monitoring configuration uses two database connections, one for alert threshold information (ALERTDEFS), and one for historical data storage via the Historian (RTVHISTORY). The default alert threshold table name is ALERTDEFS. The default history table names are CACHETOTALS and NODESTATS. Substitutions are used for the database connection names and table names which are defined in the OPTIONS.ini file found in the RTVOC_HOME/myocm/ directory.

Important Note: The default Historian configuration saves aggregated cache and node metrics only.

JDBC
JDBC driver file for selected database.

Example: ojdbc14.jar

The location of the JDBC driver must be available on the JAVA classpath. The path to the driver can be added to the RTV_USERPATH variable in conf/ocm_setup.(bat or sh).

JDBC access parameters such as user name, password, driver class and driver URL.

Example:

User Name: kermit
Password: frog

Driver: oracle.jdbc.driver.OracleDriver
URL: jdbc:oracle:thin:@dbhost:1521:rtv

ODBC
In order for RTView to communicate with your database using an ODBC-JDBC bridge, you must have an ODBC driver for your database. Most databases that run on Microsoft Windows come standard with an ODBC driver. You must also register your database with ODBC before accessing it from RTView. The name specified for the ODBC data source name during the ODBC driver setup must be RTVHISTORY for the history table connection and ALERTDEFS for the alert parameters table connection.

Database Capacity and Purging
The OC Monitor Historian writes average values to the database every 5 minutes by default.

At the end of each interval, the last 5 minutes of real time data in the data server for the CacheTotals and NodeStats caches is averaged and written to the Historian database. One CacheTotals row is written for each cache and tier combination, and NodeStats row is written for each cluster node. Each column value is an average for the most recent compaction interval.

Database capacity for the CACHETOTALS and NODESTATS tables can be estimated with the following formula:

Bytes/day written to historian tables = ((A * 420) + (B * 154)) * 288
Where:
A = the number of cache/tier combinations.
(one cache with both front and back tiers counts as 2 for database capacity estimates)
B = the number of cluster nodes.

Table purging, archiving, displacement or additional compaction is not provided in the default Historian configuration.

The customer can provide procedures or scripts to keep the database within capacity limits.

If licensed, the Advanced Historian features for table displacement may be used.

Defining Database Connections
The database connections (referred to as SQL connections) used by the OC Monitor are defined in the following files found in the cluster project directory (myocm):

OPTIONS.ini
Read by Data Server, Builder, or Viewer during startup.
HISTORY.ini
Read by the Historian during startup.

OPTIONS.ini
The OPTIONS.ini file defines the necessary SQL connections. The default connections for HSQLDB are:

sqldb ALERTDEFS sa - jdbc:hsqldb:hsql://localhost:3380/alertdefs org.hsqldb.jdbcDriver - false true
sqldb ALERTDEFS_TAB sa - jdbc:hsqldb:hsql://localhost:3380/alertdefs_tab org.hsqldb.jdbcDriver - false true

sqldb RTVHISTORY sa - jdbc:hsqldb:hsql://localhost:3380/rtvhistory org.hsqldb.jdbcDriver - false true

Where:
sa = the username and password for HSQLDB. The ‘-‘ means that a password is not required for the HSQLDB sa account.

HISTORY.ini
The HISTORY.ini file defines the properties for a single SQL connection. The lines in HISTORY.ini that define the default HSQLDB connection properties are:

driver org.hsqldb.jdbcDriver
url jdbc:hsqldb:hsql://localhost:3380/rtvhistory

username sa

Note that a line for the password property does not appear because it is not needed for the HSQLDB sa account. The properties that appear in HISTORY.ini should match the components of the RTVHISTORY connection defined in OPTIONS.ini.

Modifying Database Connections
If you replace HSQLDB with another database, the database connections in HISTORY.ini and OPTIONS.ini must be modified for the database. Template files are provided for this in the dbconfig directory.

To use the template files:

1. Replace HISTORY.ini with the appropriate HISTORY_<database>.ini file from the dbconfig directory, where <database> corresponds to your type of database (for example, HISTORY_mysql.sql).

2. Edit the OPTIONS.ini file in the new directory and replace the following lines with the content from the OPTIONS_<database>.ini file from the dbconfig directory.

        sqldb ALERTDEFS sa - jdbc:hsqldb:hsql://localhost:3380/alertdefs org.hsqldb.jdbcDriver - false true
        sqldb ALERTDEFS_TAB sa - jdbc:hsqldb:hsql://localhost:3380/alertdefs_tab org.hsqldb.jdbcDriver - false true
        sqldb RTVHISTORY sa - jdbc:hsqldb:hsql://localhost:3380/rtvhistory org.hsqldb.jdbcDriver - false true

3. Make the following edits to the HISTORY.ini and OPTIONS.ini files as they apply to your database:

        myusername - Replace with the username with which you connect to the database.
        mypassword - Replace with the password with which you connect to the database.
        myhost - Replace with the hostname or IP address of the system where the database resides.
        myinstance - Replace with the name of the database instance used. This may be your username in some cases.

4. If you need to provide encrypted passwords (rather than expose server password names in a clear text file), do the following. If not, skip this step.

	To provide encrypted passwords, use the “encode_string” utility:

	In an initialized command window, execute the following script where *mypassword* is your plain text password (this password will be encrypted).
		encode_string sql mypassword
	You then receive an encrypted password for copying and pasting into the password field. For example:
		encrypted value: 013430135501346013310134901353013450134801334

Defining Database Tables
The dbconfig directory contains .sql template files to assist you in creating the correct tables in the database of your choice. The standard SQL syntax is provided for each database, but requirements can vary depending on database configuration. Consult with your database administrator, or contact SL Technical Support, if you require assistance.

To define the database tables using the provided template files, perform the following steps.

1. In the dbconfig directory, open the createtables_<database>.sql file, where <database> corresponds to your type of database (for example, createtables_mysql.sql).

Make the following edits as they apply to your database:

myinstance: Replace with the database instance where you wish to create the table.
mydbuser: Replace with the database user whose instance the tables will be created under.

2. Use the edited .sql file to create the database tables. The effective method for doing this will vary depending on your database and how that database is configured. Some possible mechanisms are:

Interactive SQL Tool - Some database applications provide an interface where you can directly type SQL commands. Copy/paste the contents of the appropriate createtables_<database>.sql file into this tool.
Import Interface - Some database applications allow you to specify a .sql file containing SQL commands. You can use the createtables_<database>.sql file for this purpose. In some cases it may be necessary to save the statements in that file into individual files.
Third Party Application - Third party tools are available for connecting to a variety of databases (RazorSQL, SQLMaestro, Toad, etc). If your database does not have either of the two above capabilities, a third party tool can be used to enter SQL commands or import .sql files.

3. Configure the OC Monitor to use the database tables you just created by editing the table names in your Cluster Property file, located in the conf directory. You can use the default table names or use your own table names. The following is an example from a sample Cluster Property file:

ocm.cachetotals_sub=-sub:$CACHETOTALS_TABLE:CACHETOTALS_MyClusterName
ocm.nodestats_sub=-sub:$NODESTATS_TABLE:NODESTATS_MyClusterName
ocm.alertdefs_sub=-sub:$ALERTDEFS_TABLE:ALERTDEFS_MyClusterName
ocm.alertdefs_tab_sub=-sub:$ALERTDEFS_TAB_TABLE:ALERTDEFS_TAB_MyClusterName


	To use the default table name, remove _MyClusterName from the line. For example:
		ocm.cachetotals_sub=-sub:$CACHETOTALS_TABLE:CACHETOTALS ocm.nodestats_sub=-sub:$NODESTATS_TABLE:NODESTATS ocm.alertdefs_sub=-sub:$ALERTDEFS_TABLE:ALERTDEFS ocm.alertdefs_tab_sub=-sub:$ALERTDEFS_TAB_TABLE:ALERTDEFS_TAB

	To change a default table name, remove _MyClusterName from the line and replace the CACHETOTALS, NODESTATS, ALERTDEFS or ALERTDEFS_TAB table name with your table name. For example:
		ocm.cachetotals_sub=-sub:$CACHETOTALS_TABLE:NYC_CACHE ocm.nodestats_sub=-sub:$NODESTATS_TABLE:NYC_STATS ocm.alertdefs_sub=-sub:$ALERTDEFS_TABLE:NYC_ALERTDEFS ocm.alertdefs_tab_sub=-sub:$ALERTDEFS_TAB_TABLE:NYC_ALERTDEFS_TAB

RTView contains components licensed under the Apache License Version 2.0.

JMS, JMX and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. They are mentioned in this document for identification purposes only.

SL, SL-GMS, GMS, RTView, SL Corporation, and the SL logo are trademarks or registered trademarks of Sherrill-Lubinski Corporation in the United States and other countries. Copyright © 1998-2011 Sherrill-Lubinski Corporation. All Rights Reserved.