Tom Roehr, Senior Consultant

Previously, my colleague Jim Hannan, wrote an introductory blog about Oracle’s OS Watcher Black Box. I’d like to review OS Watcher and add some additional information that I have found useful.

What is OS Watcher Black Box?

OS Watcher Black Box (OSWBB) is provided by Oracle to automate gathering of UNIX system performance statistics and analysis.

OSWBB consists of two parts:

OSWBB – A collection of shell scripts that uses existing system performance tools like vmstat, iostat, etc to gather information.
OSWBBA – A java application, oswbba.jar, to analyze the collected data.

Obtaining OSWBB

To download OSWBB, you will need a My Oracle Support account (MOS). Log into MOS at http://support.oracle.com.

You can then directly download OSWBB’s tar file from this link:

https://support.oracle.com/epmos/main/downloadattachmentprocessor?attachid=301137.1:OSW_file

The current download is oswbb732.tar.

Installing OSWBB

Installation involves simply un-tarring the downloaded file from Oracle Support. Copy the file into the directory where you want to install OSWBB and then run the following tar command:

$ tar xvf oswbb732.tar

OSWBB will then be installed into the directory oswbb. For the rest of this document, that directory will be referred to as <OSWBB_HOME>.

Running OSWBB

Starting from command line is straightforward.

$ cd <OSWBB_HOME>

$ ./startOSWbb.sh

Unfortunately, OSWBB will stop gathering statistics if that shell session is ended. Since the specific purpose of OSWBB is to continuously gather systems statistics, I use the cron scheduling application to make sure it’s always running.

You can enable it via cron with the following crontab entry.

* * * * *     cd /home/oracle/oswbb;./startOSWbb.sh 2>&1 > /dev/null

For this example, OSWBB was installed in the Oracle home directory, so <OSWBB_HOME> is /home/oracle/oswbb. The start script, startOSWbb.sh, always checks to see if it’s currently running before it starts the monitoring scripts. Scheduling it to run every minute ensures minimal loss of statistics in case of system reboots or other events that terminates OSWBB.

Adding NFS statistics

By default, OSWBB will not collect NFS statistics from iostat. You can enable NFS statistic gathering in OSWBB by editing the OSWatcher.sh script in <OSWBB_HOME> and changing the line with nfs_collect from nfs_collect=0 to nfs_collect=1.

Setting up a RAC Private Network

OSWBB has hooks in place to monitor the private interconnect network between RAC nodes. You enable this by creating an executable shell script named private.net in the <OSWBB_HOME> directory, with traceroute commands set up for your RAC environment.

The file Exampleprivate.net located in <OSWBB_HOME> shows examples for the following operating systems:

• Solaris
• HP-UX
• Tru64
• Linux
• AIX

Extending OSWBB to run your own checks

OSWBB has provisions for running additional statistics gathering. You need to create the file extras.txt in the <OSWBB_HOME> directory to specify the extra commands you would like to run.

Examples of enabling statistic gathering with the UNIX commands du, sar, and uptime are shown in the file Example_extras.txt, along with the shell scripts call_du.sh, call_sar.sh, and call_uptime.sh.

Generating Reports with OSWBBA

OS Watcher Black Box Analyzer (OSWBBA) is a Java application included in the OSWBB download. It provides analysis on the collected statistics and identifies performance areas of concern.

To use OSWBBA, you will need a Java Runtime Environment (JRE) version 1.4.2 or greater. Fortunately, Oracle Database installations include one. To use the Oracle Database JRE, add it to your executable path with the following commands:

$  PATH=$ORACLE_HOME/jdk/jre/bin:$PATH

$ export PATH

OSWBBA can be run interactively or from the command line. By using the command line options, running analysis reports can be scheduled via cron.

The following command example runs OSWBBA for one day:

$ java -jar oswbba.jar -i archive -B Feb 12 00:00:00 2015 -E Feb 13 00:00:00 2015 -A

The -B and -E flags set the beginning and end of the of the analysis period. The -A flag produces a text analysis output file. You can optionally provide a filename after the -A flag to override the default filename generation. Optionally, replacing the -A flag with the -P flag will generate a HTML version of the analysis report including performance graphs.

Conclusion

OSWBB simplifies the task of gathering performance statistics for the DBA. By using it with UNIX utilities like cron, a DBA can have the database servers’ performance analyzed automatically to help identify problems with system resources.

References

Note: You will need a My Oracle Support account to access the following links:

OSWatcher (Includes: [Video])           Document 301137.1

OSWatcher User Guide                      Document 1531223.1

OSWatcher Analyzer User Guide      Document 461053.1