oswbba
THE OSWATCHER ANALYZER USER'S GUIDE
Carl Davis
Center of Expertise
September 5, 2014
To see how to use this tool and it's different features you can view a series of short "how to do" videos in document 301137.1
Contents
Introduction
The OSWatcher Analyzer (oswbba) is a graphing and analysis utility which comes bundled with OSWatcher v4.0 and higher. oswbba allows the user to graphically display data collected, generate reports containing these graphs and provides a built in analyzer to analyze the data and provide details on any performance problems it detects. The ability to graph and analyze this information relieves the user of manually inspecting all the files.
NOTE: oswbba replaces the utility OSWg. This was done to eliminate the confusion caused by having multiple tools in support named OSWatcher. oswbba is only supported for data collected by oswbb and no other tool.
Best Practices
Pro-Active Problem Avoidance and Diagnostic Collection
Although some problems may be unforeseen, in many cases problems may be avoidable if signs are detected early enough. Additionally, if an issue does occur, it is no use collecting information about that issue after the event. oswbb is one of the tools that support recommend for collecting such diagnostics. For information on suggested uses, other proactive preparations and diagnostics, see:
Document 1482811.1
Best Practices: Proactively Avoiding Database and Query Performance Issues
Document 1477599.1
Best Practices Around Data Collection For Performance Issues
Back to Contents
Overview
oswbba is written in java and requires as a minimum java version 1.4.2 or higher. oswbba can run on any Unix X Windows or PC Windows platform. An X Windows environment is required because oswbba uses Oracle Chartbuilder which requires it.
oswbba parses all the oswbb vmstat, iostat ,netstat, ps and top utility log files contained in an archive directory. Once the data is parsed, the user is presented with a command line menu which has options for both displaying graphs, creating binary gif files of these graphs, generating an html report containing all the graphs with narrative on what to look for, and the ability to self-analyze the files oswbb creates.
Back to Contents
Supported Platforms
oswbba is certified to run on the following platforms:
- AIX
- Solaris
- HP-UX
- Linux
- Windows
Back to Contents
Installing oswbba
oswbba requires no installation. It comes shipped as a standalone java jar file with oswbb v4.0.0 and higher.
Back to Contents
Starting oswbba
Before starting the oswbba utility you must have java version 1.4.2 or higher installed on your system. Java can be downloaded for free fromhttp://www.java.com. Also if you are running Oracle you have already a version of java installed. To verify you have the correct version of java installed on your system issue the following command...
This should be version 1.4.2 or higher. If not, contact your system administrator to get the current version of java installed. Alternatively, you can use the version of java that comes shipped with Oracle. Here is an example of using the version of java that comes shipped with the database...(depending upon the version of the database, the jre may be in a different location)
| //Note: the location of the jre is in $ORACLE_HOME/jre/1.4.2/bin
//now put this location in the UNIX PATH:
$ export PATH=$ORACLE_HOME/jre/1.4.2/bin:$PATH |
Once the correct version of java has been verified, you can start oswbba. oswbba requires an input directory to run. To specify the input directory you must use the -i option. The input directory is the fully qualified path name of an archive directory containing oswbb logs. The archive directory must be the same directory structure as the archive directory for oswbb. It must contain the respective subdirectories--oswvmstat, oswiostat, oswps, oswtop, oswnetstat, etc. If you are running Linux, then additional directories are also created. It is very important to note the program requires an archive directory not an individual log directory.
| $java -jar oswbba.jar -i /u02/home/osw/archive Starting OSWbba V7.0
OSWatcher Analyzer Written by Oracle Center of Expertise
Copyright (c) 2012 by Oracle Corporation Parsing Data. Please Wait... Enter 1 to Display CPU Process Queue Graphs
Enter 2 to Display CPU Utilization Graphs
Enter 3 to Display CPU Other Graphs
Enter 4 to Display Memory Graphs
Enter 5 to Display Disk IO Graphs Enter 6 to Generate All CPU Gif Files
Enter 7 to Generate All Memory Gif Files
Enter 8 to Generate All Disk Gif Files Enter L to Specify Alternate Location of Gif Directory
Enter T to Specify Different Time Scale
Enter D to Return to Default Time scale
Enter R to Remove Currently Displayed Graphs
Enter A to Analyze Data
Enter S to Analyze Subset of Data(Changes analysis dataset including graph time scale
Enter P to Generate A Profile
Enter Q to Quit Program Please Select an Option: |
oswbba parses all the archive files in memory prior to generating graphs or performing an analysis. If you have a large amount of files to parse you may need to allocate more memory in the java heap. If you experience any error messages regarding out of memory such as java.lang.OutOfMemoryError, you may have to increase the size of the java heap. To increase the size of the java heap use the -Xmx flag.
| $java -jar -Xmx512M oswbba.jar -i /u02/home/oswbb/archive Starting oswbba V7.0
OSWatcher Analyzer Written by Oracle Center of Expertise
Copyright (c) 2012 by Oracle Corporation Parsing Data. Please Wait... |
Back to Contents
Stopping oswbba
To stop the oswbba utility select option "Q" from the menu.
Back to Contents
Using oswbba
oswbba has multiple user interface options. If oswbba is started as above, the user will be able to choose from a list of options on a menu. In all cases oswbba must be supplied the archive directory location with the -i flag. Not all of the disk I/O options will be available to all users. These options are only available for solaris, linux and aix, and only if iostat is collected with the extended disk statistics option. These options will also not be available if oswbba encountered any parsing issues while parsing iostat archive files.
Previously if a user wanted to analyze the archive all files in the archive would be analyzed automatically. In release 7.0, the begin and end times can be specified to limit the analysis to a particular time of interest. This can be controlled by using the command line options -b and -e. These options are available if you run from the command line or can be chosen from the menu with the -S option. To use this option you must specify the beginning or start time and the ending or stop time. If you do not specify a valid begin/end time, the program will default to using the first and last timestamps in your archive directory. Please see the oswbba_README.txt document located in the oswbb/docs/TheAnalyzer directory for examples on how to use this option.
Example. In this example your archive contains 17 hours worth of data in the oswvmstat directory. You want to only analyze files starting at.13.01.09.1300 through 13.01.09.2000
| $ls coesrv40.us.oracle.com_vmstat_13.01.09.1300.dat
coesrv40.us.oracle.com_vmstat_13.01.09.1400.dat
coesrv40.us.oracle.com_vmstat_13.01.09.1500.dat
coesrv40.us.oracle.com_vmstat_13.01.09.1600.dat
coesrv40.us.oracle.com_vmstat_13.01.09.1700.dat
coesrv40.us.oracle.com_vmstat_13.01.09.1800.dat
coesrv40.us.oracle.com_vmstat_13.01.09.1900.dat
coesrv40.us.oracle.com_vmstat_13.01.09.2000.dat
coesrv40.us.oracle.com_vmstat_13.01.09.2100.dat
coesrv40.us.oracle.com_vmstat_13.01.09.2200.dat
coesrv40.us.oracle.com_vmstat_13.01.09.2300.dat
coesrv40.us.oracle.com_vmstat_13.01.10.0000.dat
coesrv40.us.oracle.com_vmstat_13.01.10.0100.dat
coesrv40.us.oracle.com_vmstat_13.01.10.0200.dat
coesrv40.us.oracle.com_vmstat_13.01.10.0300.dat
coesrv40.us.oracle.com_vmstat_13.01.10.0400.dat
coesrv40.us.oracle.com_vmstat_13.01.10.0500.dat java -jar oswbba.jar -i archive -b Jan 9 13:15:00 2013 -e Jan 19 13:30:00 2013 -s |
Back to Contents
Using oswbba: Menu Option
oswbba can be run with a menu driven user interface. This option gives the user the most flexibility and allows graphs to be displayed real-time. To start oswbba with the menu option issue the following on the command line...
| java -jar oswbba.jar -i <fully qualified path name of an oswbb archive directory> |
After starting oswbba, a set of options will display. Enter an option value and hit return.
| OPTIONS The following options are supported: |
| 1..3 |
These options display graphs of specific CPU components of vmstat. Option 1 displays the process run, wait and block queues. Option 2 displays CPU utilization graphs for system, user and idle. Option 3 displays graphs for context switches and interrupts. |
| 4 |
This option displays memory graphs for free memory and available swap.. |
| 5 |
This option uses the extended disk statistics option of iostat to display a list of all devices for solaris, aix and linux platforms only. The device name along with the average service time of each device is then listed. The user then selects one of the devices out of the list of devices. Graphs are available for reads/second, writes/second, service time and percent busy. |
| 6..8 |
These options generate images of the graph to a file without displaying them to the screen. All graphs for that specific category, CPU, memory or IO will be generated and placed in the directory where oswbba is located. To override this directory and name an alternative location to place these files use option L discussed below. |
| L |
User specified location of an existing directory to place any gif files generated by oswbba. This overrides the oswbba automatic convention for placing all gif files in the /gif directory. This directory must pre-exist! |
| A |
This option analyzes the files in the archive and produces a report. |
| S |
This option analyzes a subset of the data in the oswbb directory and produces a report in the analysis directory. |
| P |
Generates an html profile. |
| T |
By default OSWbba parses all the OSWbb log files contained in the input directory and the default graphs are based on the entire time span of all the logs. By default, OSWbb keeps the last 48 hours of logs in the archive. This means the default graph will graph all 48 hours of of data. This option allows the user to specify a different subset of times within the entire collection . An example would be only to graph a 2 hour period out of the entire 48 hour collection. |
| D |
This option resets the graphing timescale back to the time encompassing the entire log collection. |
| R |
This option removes all previously displayed graphs from the screen. |
| Q |
Exits the program. |
Back to Contents
Using oswbba: Command Line Option
All graphing, profile and analysis options are available to be passed into oswbba from the command line. Only the -i option is required. Use the table below to add additional options.
| java -jar oswbba.jar -i <fully qualified path name of an osw archive directory> -P <name> -L <name> -6 -7 -8
Example:
java -jar oswbba.jar -i archive -6 -7 -P tuesday_crash |
| OPTIONS The following options are supported: |
| -i |
<archive dir> Required. This is the input archive directory location. |
| -6 |
Same as option 6 from the menu. Will generate all cpu gif files. |
| -7 |
Same as option 7 from the menu. Will generate all memory gif files. |
| -8 |
Same as option 8 from the menu. Will generate all disk gif files. |
| -L |
<location name> User specified location of an existing directory to place any gif files generated by OSWbba. This overrides the OSWbba automatic convention for placing all gif files in the /gif directory. This directory must pre-exist! |
| -A |
<analysis name> Same as option A above. This option analyzes the files in the archive directory and produces a report |
| -S |
<analysis name> Same as option S above. This option analyzes a specific subset of times of the files in the archive directory and produces a report. This option is used together with the -B and -E options |
| -START |
<filename>Used with the analysis option to specify the first file located in the oswvmstat directory to analyze. |
| -STOP |
<filename>Used with the analysis option to specify the last file located in the oswvmstat directory to analyze. |
| -P |
<profile name> User specified name of the html profile generated by OSWbba. This overrides the oswbba automatic naming convention for html profiles. All profiles whether user specified named or auto generated named will be located in the /profile directory. |
| -B |
<begin time> Same as option T from the menu. The begin time will allow the user to select a begin time from within the archive of files to graph/profile. This overrides the default start time which is the earliest time entry in the archive directory. The format of the start time is Mon DD HH:MM:SS YYYY. (Example :Jul 25 11:58:01 2007). An invalid begin time will result in using a default value of the first timestamp in your archive. |
| -E |
<end time> Same as option T from the menu. The end time will allow the user to select an end time from within the archive of files to graph/profile. This overrides the default end time which is the latest time entry in the archive directory. The format of the end time is Mon DD HH:MM:SS YYYY. (Example :Jul 25 11:58:01 2007).An invalid end time will result in using a default value of the last timestamp in your archive. . |
| -NO_IOSTAT |
<filename> Ignores files in the oswiostat directory from analysis. |
| -NO_TOP |
<filename> Ignores files in the oswtop directory from analysis. |
| -NO_PS |
<filename> Ignores files in the oswps directory from analysis. |
| -NO_NETSTAT |
<filename> Ignores files in the oswnetstat directory from analysis. |
| -NO_LINUX |
<filename> Ignores files in the oswmeminfo directory from analysis. |
| -MEM_ALL |
<filename> Analyzes virtual and resident memory allocation for all processes. This is very resource intensive. |
Back to Contents
Ignoring certain directories from analysis
Because the archive directory can contain gigabytes worth of data, the analyzer can take some time to analyze extremely large files. The analyzer parses these files and stores the data into memory structures that grow in size as more files are parsed. Once oswbba has reached the maximum size specified by the jvm, each additional file will take longer to process. This is normally only a problem if you have many days worth of data or you have thousands of processes on the machine making for large ps files. If you find this to be the case you can eliminate certain directories from being analyzed. You can not however, eliminate vmstat data because this data is critical to any analysis performed by oswbba. There also may be times when resources on the machine may not be available to allow this kind of heavier processing. By eliminating the oswps directory, this more intensive data parsing and analysis can be eliminated or postponed until a later time. To eliminate specific directories from the analysis you must specify the appropriate flag when running oswbba. Flags are as follows:
| OPTIONS The following options are supported: |
| -NO_IOSTAT |
<filename> Ignores files in the oswiostat directory from analysis. |
| -NO_TOP |
<filename> Ignores files in the oswtop directory from analysis. |
| -NO_PS |
<filename> Ignores files in the oswps directory from analysis. |
| -NO_NETSTAT |
<filename> Ignores files in the oswnetstat directory from analysis. |
| -NO_LINUX |
<filename> Ignores files in the oswmeminfo directory from analysis. |
| -MEM_ALL |
<filename>Analyzes virtual and resident memory allocations for all processes. This is very resource intensive. |
An example of ignoring netstat and iostat data from analysis:
| java -jar oswbba.jar -i archive -NO_NETSTAT -NO_IOSTAT |
Sample Profile
Generating an htmp profile is a useful feature of oswbba. This html document contains all the graphs along with some text directing the user on what to look for. A sample oswbba profile can be found by clicking here.
To add database metrics consider running LTOM. To see what an LTOM profile looks like click here.
Back to Contents
Sample Charts
Back to Contents
Known Issues
Because oswbba builds graphs based on the unix operating system date function, the time stamp must be in standard English LANG format. The time stamp is formatted automatically by default (setting the parameter oswgCompliance = 1) in the OSWatcher.sh file.
Back to Contents
Reporting Feedback
If you encounter problems running oswbba which are not listed under the Known Issue section or would like to provide comments/feedback about oswbba (including enhancement requests) please send email to [email protected]
Legal Notices and Terms of Use
REFERENCES
NOTE:352363.1
- LTOM - The On-Board Monitor User Guide
NOTE:461054.1
- OSW System Profile - Sample
NOTE:301137.1
- OSWatcher (Includes: [Video])
NOTE:1482811.1
- Best Practices: Proactively Avoiding Database and Query Performance Issues
NOTE:461052.1
- LTOM System Profiler - Sample Output
NOTE:1477599.1
- Best Practices: Proactive Data Collection for Performance Issues
