######################################################################
# Copyright (c)  2012 by Oracle Corporation
######################################################################
# Modifications Section:
######################################################################
##     Date        File            Changes
######################################################################
##  04/18/2005                      Baseline version 1.2.1 
##				              
##  05/19/2005     OSWatcher.sh     Add -x option to iostat on linux 
##  V1.3.1                          Add code to write pwd to /tmp/osw.hb
##                                  for rac_ddt to find osw archive 
##                                  files
##                                 
##  V1.3.2         OSWatcher.sh     Remove -f flag from $TOP for HP Conf
##                                  section. Append -f flag to $TOP when
##                                  running the HP top cmd   
##
##  09/29/2006     OSWatcher.sh     Added $PLATFORM key and OSW version 
##  V2.0.0                          info to header of all files. This 
##                                  will enable parsing by PTA and 
##                                  OSWg  
##
##  10/03/2006     OSWg.jar         Fixed format problem for device names 
##  V2.0.1                          greater than 30 characters   
##                                  
##  10/06/2006     OSWg.jar         Fixed linux flag to detect linux
##  V2.0.2                          archive files. Fixed bug  with
##                                  empty lists causing exceptions
##                                  when graphing data on platforms
##                                  other than solaris  
##  07/24/2007     OSWatcher.sh     Added enhancements requested by
##  V2.1.0                          linux bde. These include using a
##                                  environment variable to control the
##                                  amount of ps data, changes to top
##                                  and iostat commands, change format
##                                  of filenames to yy.mm.dd, add 
##                                  optional flag to compress files.
##                                  Added -D flag for aix iostat  
##  07/24/2007     oswlnxtop.sh     Created new file for linux top
##  V2.1.0                          collection.
##  07/24/2007     oswlnxio.sh      Created new file for linux iostat
##  V2.1.0                          collection.   
##  07/24/2007     startOSW.sh      Added optional 3rd parameter to 
##  V2.1.0  
##  11/26/2007     oswlnxtop.sh     Fixed bug with awk script. Bug caused 
##  V2.1.1                          no output on some linux platforms  
##  12/16/2008     OSWg.jar         Fixed problem reading aix
##  V2.1.2                          iostat files   
##  07/31/2009     OSWatcher.sh     Release 3.0 for EXADATA
##  V3.0.0                                                                                         
##  02/11/11       OSWg.jar         Fixed bug with linux iostat entries
##  V3.0.1                          spanning multile lines
##  05/04/11                        Fixed directory permission on
##  V3.0.2                          install of osw.tar
##  02/01/12                        Release 4.0 
##  V4.0.0
##  06/18/12                        Release 5.0 
##  V5.0.0
##  08/15/12                        Release 5.1 
##
##  V5.1.1         OSWbba,jar       Ignore compressed files
##  08/22/12                        when analyzing
##  V5.2.0         OSWatcher.sh     Multiple bug fix release
##  11/7/12                         fix vmstat inserting corrupt data
##                 oswbba.jar       fix linux memory status = unknown
##  V6.0.0                          Release 6.0 
##  02/11/13
##  V7.0.0                          Release 7.0 
##  10/17/13
##  V7.1.0                          Release 7.1 
##  01/14/14    
##  V7.2.0                          Release 7.2 
##  04/29/14   
##  V7.3.0                          Release 7.3 
##  05/28/14   
##  09/05/14       OSWatcher.sh     fix bug with oswifconfig directory
##  V7.3.1         OSWatcherFM.sh   not purging 
##  09/17/14       OSWatcher.sh     fix bug for oswnfs directory
##  V7.3.2
##  02/27/17       OSWatcher.sh     fix bug in AIX top collection.
##  V7.3.3         startOSWbb.sh    all add support for all
##                 xtop.sh          internation date support
##  04/17/17       OSwatcher.sh
##  V8.0.0         OSWatcherFM.sh   Release 8.0.0
##  V8.1.0         OSwatcher.sh               
##  08/25/17       OSWatcherFM.sh   Release 8.1.0
######################################################################
WHAT'S NEW IN THIS RELEASE:

New data collection for HP-UX. A new directory named oswsar will store
contents of sar -d to supplement existing i/o collection.

New data collection for Linux. cpuinfo will not be captured but this will 
be a single capture and not taken at the snapshot interval sample rate.

Heartbeat file located in /tmp/osw.hb will be removed on shutdown.

New analyzer updates.

######################################################################
OSW (OSWatcher) is a series of UNIX shell scripts used to collect OS 
and network metrics. These metrics are then archived to ascii files. 
This tool runs continuously but saves only the last x number of hours 
of data. The output of the tool resides in the archive subdirectory.
######################################################################
INSTALLATION:

Once the tool has been downloaded to the directory you wish to install,
untar the oswbb.tar file. This will create a directory called oswbb. The 
oswbb files are then untared into this new directory. Next, make sure to 
change the file permissions on these files to execute by using chmod.
$ chmod 744 *
######################################################################
LOCATION:

OSWbb writes it's location in a heartbeat file named osw.hb in the /tmp
directory. This is done so other oracle utilities like RAC-DDT and RDA
can find OSWbb data when these utilities are run. This file gets
removed when OSWatcher is stopped.
######################################################################
RAC USERS:

OSWbb needs to be installed on each node in the cluster. If installing
on a shared file system then install each node's OSWbb into a unique 
directory.  
######################################################################
CONFIGURATION:

This tool collects the following kinds of data using the resident host
os utilities. Make sure these utilities are in your PATH and that you
have permission to execute them...

Example:

    NETSTAT=Configured in file osw.net
    IOSTAT='iostat 1 3'
    VMSTAT='vmstat 1 3 '
    TOP=Configured in file xtop.sh
    PSELF=Configured in psmemsub.sh
    MPSTAT='mpstat 1 3' 
    IFONFIG='ifconfig -a'
    
To change or reconfigure the tool to use different arguments to the 
underlying host utility edit the OSWatcher.sh file (Look for the 
section CONFIGURATION). The tool comes preconfigured for each UNIX os by 
default. Oracle Support recommends you use the recommended 
configuration and do not modify unless instructed by Oracle Support.

######################################################################
CONFIGURATION: ADDING CUSTOM DATA COLLECTIONS

You can have OSWbb run your own shell scripts and automatically store
and manage the data in the same way OSWbb collects and manages the data
it collects like vmstat, iostat, etc. This callable interface is provided 
"as is" and is not supported. You must write and test your own scripts
and then link them to oswbb with this interface. The example provided
is a very simple example of calling a standard UNIX utility.

Step 1: Create an executable shell script and place it in the oswbb
directory. In that file put the following header lines at the top of
the file:

#!/bin/sh
echo "zzz ***"`date '+%a %b %e %T %Z %Y'` >> $1


Step 2: Redirect the output of your script or UNIX command to $1.
$1 is the OSWbb archive directory where OSWbb writes all the files it
collects. In the following example the output of running the du 
command will be redirected to $1 (the oswbb archive directory).

Example:

du >> $1

See the example du.sh which is provided in the oswbb directory.


Step 3: Add a new entry in the file extras.txt for that file. See
extras.txt for format of the entry.

In the above example, OSWbb will run the du command in this script at
the same interval all other commands are run. The output of the
script will be in the archive directory.

The sample script du.sh is provided in the oswbb directory. You can 
review it along with the examples in extras.sh to see how to call your
scripts.
######################################################################
OPTIONAL UNIX ENVIRONMENT VARIABLES:

A new optional environment variable to control the location of the
archive directory is now available. By default, oswbb will create the
archive directory as a subdirectory named archive in the location 
where oswbb is installed. To override this default location:

export OSWBB_ARCHIVE_DEST= <new location> or
use the optional 4th argument when starting oswbb to specify the location
(see the starting OSWbb section below for more details)

Example:
export OSWBB_ARCHIVE_DEST=/usr/app/archive

This will cause the archive directory to be created in this new location
(/usr/app/archive) and not created under the home oswbb directory.

A second optional environment variable to control the amount of samples
the ps command collects is available. This can be done by specifying

export OSW_PS_SAMPLE_MULTIPLIER=n
where n = number of samples to skip

Example:
export OSW_PS_SAMPLE_MULTIPLIER=3 

OSWatcher  is started with a default value of 20 seconds. This would
cause ps data to be collected 1 time every 60 seconds (20 * 3) instead
of every 20 seconds.
######################################################################
MONITORING PRIVATE NETWORKS:

OSWatcher will automatically generate traceroute information and create
a file named private.net. It is recommended that OSWatcher configure
traceroute information automatically.
Alternatively, you use configure the traceroute command manually by 
creating the file private.net. Create a file named private.net in the 
oswbb directory. As an example, look at the Exampleprivate.net file 
and manually enter in the hostname or ipaddress you wish to monitor. 
Each UNIX os uses slightly different arguments to the traceroute 
command. Refer to Exampleprivate.net for examples for each UNIX os.
######################################################################
OSWBBA DATE COMPLIANCE:

To force the UNIX date mask to comply with OSWbba formatting,  the
parameter oswgCompliance by default is now set to 1.

oswgCompliance=1

Setting this parameter will force a date mask that is readable by OSWbba
for vmstat, iostat and top files. This parameter will not change the date
mask in any other files. Set this parameter to 0 if you do not want the date
change for analysis by OSWbba.
######################################################################
EXADATA:

Exadata users must run OSWatcher as the root user. Failure to do so
will result in a warning and the shutdown of OSWatcher.
######################################################################
STARTING OSWbb:

To start the OSWbb utility execute the startOSWbb.sh shell script. This 
script has 2 arguments which control the frequency that data is 
collected and the number of hours worth of data to archive. An optional
3rd and 4th argument are also available (see below)

ARG1 = snapshot interval in seconds.
ARG2 = the number of hours of archive data to store.
ARG3 (optional) = the name of the zip utility to run if the user wants to
                  compress the files automatically after creation.
ARG4 (optional) = the fully qualified name of the archive directory
                  where you want oswbb to save your data. This option can
                  be used instead of setting the UNIX environment variable
                  OSWBB_ARCHIVE_DEST. If this parameter is not set oswbb 
                  will look for the UNIX environment variable 
                  OSWBB_ARCHIVE_DEST. If neither are set the archive 
                  directory will remain in the default location under
                  the oswbb directory                  
                  
                  
If you do not enter any arguments the script runs with default values 
of 30 and 48 meaning collect data every 30 seconds and store the last 48 
hours of data in archive files.

Example 1:

./startOSWbb.sh 60 10
This would start the tool and collect data at 60 second intervals and 
log the last 10 hours of data to archive files.

Example 2:

./startOSWbb.sh
This would use the default values of 30, 48 and collect data at 30 
second intervals and log the last 48 hours of data to archive files.

Example 3:

./startOSWbb.sh 20 24 gzip
This would start the tool and collect data at 20 second intervals and 
log the last 24 hours of data to archive files. Each file would be
compressed by running the gzip utility after creation.
######################################################################
STOPPING OSWbb:

To stop the OSWbb utility execute the stopOSWbb.sh command. This 
terminates all the processes associated with the tool.

Example:

./stopOSWbb.sh
######################################################################
SENDING OSWATCHER DATA INTO SUPPORT:

Two utilities have been provided to bundle OSWatcher data. We expect
OSWatcher data to be collected and bundled in such a way as to maintain
the existing directory structure created by running the tool. Failure 
to bundle OSWatcher data will prevent the automatic processing and 
analysis of the data and prolong the response you receive by opening
an SR with support.

To bundle the entire OSWatcher data collection use the script 
tar_up_full_archive.sh. This script prompts you to enter the fully
qualified path name of the archive directory and creates a tarball
named osw_archive.tar that you can upload to an SR.

To bundle a specific time window, which can come in handy if you have
a very large OSWatcher archive, or just want to send a subset of the 
data for a specific time window use script tar_up_partial_archive.sh. 
This script prompts you to enter the fully qualified path name of 
the archive directory and then prompts for a starting and ending log.
The script creates a tarball named osw_archive.tar that you can upload 
to an SR.

Example:

./tar_up_full_archive.sh
######################################################################
KNOWN ISSUES:

Note that if you haven't installed net-tools on Oracle Linux 7 you may
see warnings when starting OSWatcher that it can't find netstat and 
ifconfig. This appears to be OL 7 specific.

You may get a warning that /proc/slabinfo does not exist. It does exist, 
but the permissions have changed to 0400 and the file is owned by root:root. 

There may be issues with the analyzer parsing timestamps that are not
standard English Language timestamps. Setting the parameter 
oswgCompliance=1 (default) should resolve this. There have been reported
cases where this alone did not correct the problem. As a workaround try
adding the LANG environment in startOSWbb.sh.

# set LANG environment
export LANG=en_US.UTF8
# Start OSW
./OSWatcher.sh $1 $2 $3 $4 &
######################################################################
# User Guide:

Please refer to the user guide contained in this docs directory for
instructions on how to use oswbb.

######################################################################
Support for oswbb:
######################################################################

For any issues or comments please email me directly carl.davis@oracle.com
######################################################################
DISCLAIMER:
This sample code is provided for educational purposes only and not 
supported by Oracle Support Services. It has been tested internally, 
however, and works as documented. We do not guarantee that it will work
for you, so be sure to test it in your environment before relying on it.

######################################################################
GETTING SUPPORT AND REPORTING PROBLEMS
======================================

Do NOT log a service request. Please email the developer directly:
carl.davis@oracle.com.

Please include a detailed description of the problem, symptom or usage 
in questions. Also, include any output generated by the script.

######################################################################
COPYRIGHT NOTICE
================

Copyright 2017, Oracle. All rights reserved.

TRADEMARK NOTICE
================

Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.

LEGAL NOTICES AND TERMS OF USE
==============================

http://metalink.oracle.com/metalink/plsql/ml2_documents.showDocument?p_database_id=NOT&p_id=225559.1


