
[1] Introduction
=======================================================================================
    Bethune Data Collect Tool (BTRobot) is coding with perl programming language,
    It can be executed with system perl (Linux/Unix) or oracle perl (Windows).

    During the period of collection, following three methods may be used:
      a. Call system command to get system related data
      b. Read system file to get configuration and logs
      c. Use oracle DBI library to query database

    For BTRobot, there are three directories in it:
      a. conf          : Directory for configuration files
      b. data          : Directory for result file, empty for a new BTRobot
      c. lib           : Directory for library and modules
      d. module        : External module used in batch mode
      e. runMe.pl      : Startup script
      f. ReadMe_CN.txt : BTRobot Help Document in Chinese
      g. ReadMe_EN.txt : BTRobot Help Document in English


[2] Options
=======================================================================================
    Opt  Message                                    Default
    ---- ------------------------------------------ ------------
     -B  Specify AWR Busy Section by hour(0 to 23)  0-23
         Format: 8-18 or 9,10,15,16 or 9-12,14-18
     -c  Specify CharacterSet/Encoding
         Format: O=GBK,A=GBK,L=GBK
                 O is database charactSet
                 A is alert logfile charactSet
                 L is listener logfile charactSet
     -d  Specify OS Modules to Skip                 (e.g. osCrontab,osListener)
         Format: osCrontab,osListener
         Desc: skip collection for specified OS modules
     -e  Specify OS Error Collect Time in Days      30
     -h  Show Robot Introduction
     -i  Specify ASM SID                            NONE
     -L  Specify Log History Limit                  30
     -M  Specify Multi-Server Config File in [conf] DBServers.conf
     -o  Specify ASM Home                           NONE
     -p  Specify Listening Port on Primary          12345
     -Q  Quit Mode, Always used in [-M] Mode
     -r  Specify AWR Data Collect Time in Days      8
     -R  Specify Top AWR Report Number              3
     -s  Specify Top Segment Limit                  10
     -S  do not Collect DG Data
     -t  Specify Alert Collect Time in Days         30
     -T  Specify Listener Collect Time in Days      30
     -u  Specify Oracle Logon Infomation            sys/oracle
     -U  Specify ASM Logon Infomation               sys/oracle
     -v  Show Robot Version
     -w  Specify Top Wait Limit                     10
     -z  do not zip Result Directory


[3] Usage
=======================================================================================
--> Firstly, we strongly recommend reading this user help
    * Note: directory may different in your server
    -----------------------------------------------------------------------------------
      cd /home/oracle/BTRobot_v2.4.0
      perl runMe.pl -h

--> For Windows
    * Note: location for perl.exe may different in your server
    -----------------------------------------------------------------------------------
      SET ORACLE_HOME=C:\oracle\product\10.2.0\db_1
      SET ORACLE_SID=WINDB
      SET PATH=%ORACLE_HOME%\bin;%PATH%         # Add oracle bin
      SET PATH=%ORACLE_HOME%\perl\bin;%PATH%    # Add oracle perl bin
      where perl             # Check whether oracle perl is existed
      sqlplus / as sysdba    # Check sys logon is OK, otherwise [-u] option may needed
      cd C:\BTRobot_v2.4.0
      perl runMe.pl

--> For Linux/Unix
    * Note: directory may different in your server
    -----------------------------------------------------------------------------------
      which perl             # Check whether system perl is existed
      sqlplus / as sysdba    # Check sys logon is OK, otherwise [-u] option may needed
      cd /home/oracle/BTRobot_v2.4.0
      perl runMe.pl

 --> Batch Collection
     * Note: this mode only used in Linux/Unix with SSH enabled
             directory may different in your server
             run batch collection on a server which can install Perl module
             and connect to all of the DB servers by ssh protocol
     -----------------------------------------------------------------------------------
       su - root                              # root is needed to install perl module
       which perl                             # Check whether system perl is existed
       cd /home/oracle/BTRobot_v2.0.0/module
       # Install Needed Perl Module
       tar -zxvf IO-Tty-1.12.tar.gz           # Install Perl Module IO-TTY/PTY
       cd IO-Tty-1.12
       perl Makefile.PL
       make
       make test
       make install
       tar -zxvf Expect-1.32.tar.gz           # Install Perl Module Expect
       cd Expect-1.32
       perl Makefile.PL
       make
       make test
       make install
       tar -zxvf Net-SSH-Expect-1.09.tar.gz   # Install Perl Module Net-SSH-Expect
       cd Net-SSH-Expect-1.09
       perl Makefile.PL
       make
       make test
       make install
       tar -zxvf Net-SCP-Expect-0.12.tar.gz   # Install Perl Module Net-SCP-Expect
       cd Net-SCP-Expect-0.12
       perl Makefile.PL
       make
       make test
       make install
       # Write DB Server Configurations, Detail see: conf/DBServers.conf
       vi conf/DBServers.conf
       # Run Collection Script in Batch Mode
       perl runMe.pl -M


[4] Interaction
=======================================================================================
--> a. RAC without user equivalence
    Generally, all nodes in RAC system is configured with user equivalence.
    In this situation, BTRobot can collect all needed data on one node.
    When RAC system without user equivalence configured, following tip shows:
    -----------------------------------------------------------------------------------
       User equivalent is not configured
       You can Choose :
       P: [Password Mode] Use Password to Login Remote and Collect Data
       L: [Listener Mode] You Must Run Command on Remote Manually (it's Default)
       ====>
    -----------------------------------------------------------------------------------
    We recommend to use [Listener Mode] to collect remote data
    [Password Mode]: input remote oracle password to collect remote data
    [Listener Mode]: execute command on remote manually to collect remote data

--> b. Waiting Remote Data
    In situation [a], when collecting remote os related data, following tip shows:
    -----------------------------------------------------------------------------------
       15:25:22     COMPLETE: BXDB -> Collection Completed, Running is [XX]
       15:26:24    cltNodRes:
       15:26:24    cltNodRes: <==================[ Attention ]==================>
       15:26:24    cltNodRes:  Follow Command Must Manual Run on Remote Node
       15:26:24    cltNodRes:  Remote List: XX
       15:26:24    cltNodRes: <==================>==================>===========>
       # ---------[ Please Run Following Command on Remote Server by Oracle ]----------
       perl -e 'use IO::Socket;use IO::Select;
       $OH=$ENV{ORACLE_HOME};my ($PN,$PP)=(" 123.123.123.123",12345); # Primary
       my $SK=IO::Socket::INET->new(PeerAddr=>$PN,PeerPort=>$PP,Proto=>TCP,Timeout=>60)
       or die "Connect [$!]";$SL=IO::Select->new($SK);$NH=($SL->handles)[0];my @FL;
       print "Files :";$NH->send("GET_FILE|X\n");die "No Reply"
       if(! $SL->can_read(60));while(1){my $ND;chomp($ND=$NH->getline);last if($ND eq
       "COMPLETED");print $ND;push(@FL,$ND);open FH,">",$ND;while(1){chomp($ND=
       $NH->getline);last if($ND eq "<-EOF->");print FH "$ND\n";}close FH;
       print "[OK] ";}print "\n";$ENV{"LIBPATH"}="$OH/lib32:$OH/lib";
       $ENV{"SHLIB_PATH"}=$ENV{"LD_LIBRARY_PATH"}=$ENV{"LIBPATH"};
       system("$OH/perl/bin/perl NodeRobot.pl $PN $PP");foreach(\@FL){unlink}'
       # -------------------------------[ Command End ]--------------------------------
    -----------------------------------------------------------------------------------
    When this tip shows, current collection task is suspend, then user must copy
    the whole command in the tip and execute it on remote server.
    * Note: in the remote command, IP Address in second line may need to changed.

--> c. Waiting DG Data
    When DG system found, following tip shows:
    -----------------------------------------------------------------------------------
       15:35:15     cltDGDat: +=============== [ DG Information ] ===============+
       15:35:15     cltDGDat: |  DG Name       Remote Host       Remote IP       |
       15:35:15     cltDGDat: |  ------------- ----------------- --------------- |
       15:35:15     cltDGDat: |  BXDG          BXDG              10.51.94.237    |
       15:35:15     cltDGDat: +==================================================+
       15:35:15     cltDGDat: Notes: You can skip DG Collection by [CTRL + C]
       # ------------------------[ Run on Remote by Oracle ]---------------------------
       perl -e 'use IO::Socket;use IO::Select;
       $OH=$ENV{ORACLE_HOME};my ($PN,$PP)=(" 123.123.123.123",12345); # Primary
       my $SK=IO::Socket::INET->new(PeerAddr=>$PN,PeerPort=>$PP,Proto=>TCP,Timeout=>60)
       or die "Connect [$!]";$SL=IO::Select->new($SK);$NH=($SL->handles)[0];my @FL;
       print "Files :";$NH->send("GET_FILE|X\n");die "No Reply"
       if(! $SL->can_read(60));while(1){my $ND;chomp($ND=$NH->getline);last if($ND eq
       "COMPLETED");print $ND;push(@FL,$ND);open FH,">",$ND;while(1){chomp($ND=
       $NH->getline);last if($ND eq "<-EOF->");print FH "$ND\n";}close FH;
       print "[OK] ";}print "\n";$ENV{"LIBPATH"}="$OH/lib32:$OH/lib";
       $ENV{"SHLIB_PATH"}=$ENV{"LD_LIBRARY_PATH"}=$ENV{"LIBPATH"};
       system("$OH/perl/bin/perl DGRobot.pl $PN $PP");foreach(\@FL){unlink}'
       # -------------------------------[ Command End ]--------------------------------
    -----------------------------------------------------------------------------------
    When this tip shows, current collection task is suspend, then user must copy
    the whole command in the tip and execute it on remote server.
    * Note: in the remote command, IP Address in second line may need to changed


[5] Configuration
    In [conf] directory, we have put some configuration files in it.
=======================================================================================
--> Config [BTConfig.pm]
    [BTConfig.pm] configuration file have most parameters for BTRobot, now it
    has five parts of configuration:
    -----------------------------------------------------------------------------------
      a. Global Parameters
      b. Global Files            -- Do not modify this part
      c. OS Collection Modules
      d. Result Files
      e. Collection Status       -- Do not modify this part
    -----------------------------------------------------------------------------------

--> a. Global Parameters
       This part of variables controls the behaviours of BTRobot when collect data.
       The meaning of them list as below :
       --------------------------------------------------------------------------------
         Name                Value            Description
         ------------------- ---------------- -----------------------------------------
         SCRIPT_VERSION      2.4.0            [Var  ] Current script's version
         ------------------- ---------------- -----------------------------------------
         ALERT_KEEP          50               [Var  ] Alert keep lines for each begining and ending of errors
         ALT_IGNORE          <Not_List_Here>  [Var  ] Error types ignored in alert collection
         CPU_MIN_IDLE        10               [Var  ] Self-Monitor minimun percentage of CPU idle, -1 means off
         DIR_MIN_SIZE        100              [Var  ] Self-Monitor minimun free space of result directory, -1 means off
         EVENT_FILTER        <Not_List_Here>  [Var  ] Wait event name in DB event collection
         ORACLE_HOME         NONE             [Var  ] Oracle Home, it comes from OS environment variable ORACLE_HOME
         ORACLE_SID          NONE             [Var  ] Oracle SID, it comes from OS environment variable ORACLE_SID
         PRINT_PROCESS       1                [Var  ] Print all process in function [getProc], do not change it
         REMOTE_LOGIN        EQUAL            [Var  ] Remote login method, it set in interactive mode when RAC without SSH user equivalence
         SKIP_STEP           0                [Var  ] Skip some waiting steps (such as DG), do not change it
         SM_INTERVAL         5                [Var  ] Self-Monitor interval in seconds, 0 means off
         SQL_BATCH_SIZE      200              [Var  ] Batch size to collect SQL-Releated data
         SYSSTAT_FILTER      <Not_List_Here>  [Var  ] Sysstat name in DB sysstat collection
         TARGET_CHARSET      UTF8             [Var  ] Target file character, do not change it
         TMOD_FILTER         <Not_List_Here>  [Var  ] Time modle name in DB time modle collection
         TOP_SQL             32               [Var  ] AWR top SQL limits
         ------------------- ---------------- -----------------------------------------
         ASM_DIAG            NONE             [Var *] ASM diagnostic dest
         CLT_TIME                             [Var *] Package collection time
         DB_NAME                              [Var *] DB name
         DB_ROLE                              [Var *] DB role
         DB_VERSION                           [Var *] DB version
         DBID                0                [Var *] DBID
         EXTINST_TYPE        DG               [Var *] Extra-Instances type (DG/OTHER), do not change it
         GLOBAL_ERROR                         [Var *] Global error message
         HOSTIP              127.0.0.1        [Var *] Current node IP
         HOSTNAME            HOSTNAME         [Var *] OS name
         INST_COUNT          0                [Var *] Instance count
         INST_TYPE           DB               [Var *] Instance type [DB/ASM], do not change it
         INSTANCE_LIST                        [Var *] Instance list for Extra-Instance collection
         LISTEN_NODE         NONE             [Var *] Package Listen node
         MIN_SNAP            0                [Var *] Minimun snapshot ID in AWR data collection
         MONITOR_PID         1                [Var *] Self-Monitor process ID
         OBJ_SCHEMA                           [Var *] Object schema for Variable replace in SQL-Releated data collection
         OS_TYPE             Linux            [Var *] OS type
         OS_USER             oracle           [Var *] OS login user
         PATH                                 [Var *] OS path variable, it comes from OS environment variable PATH
         SQL_LIST                             [Var *] List for variable replace in SQL-Releated data collection
         TRACE_LIMIT         51200            [Var *] Trace size limit, collection size for begining and ending of one trace
         UNIQUE_NAME                          [Var *] DB unique name
         ------------------- ---------------- -----------------------------------------
         DB_CHARSET          NONE             [Param] -c: DB Character
         OS_CHARSET          NONE             [Param] -c: OS Character
         ALT_CHARSET         NONE             [Param] -c: Alert Character
         LSN_CHARSET         NONE             [Param] -c: Listener Character
         OSERR_TIME          30               [Param] -e: OS Error Log Limit by Day
         ASM_SID             NONE             [Param] -i: ASM SID
         LOG_LIMIT           30               [Param] -L: Log History Limit by Day
         ASM_HOME            NONE             [Param] -o: ASM Home
         LISTEN_PORT         12345            [Param] -p: Script Listen Port
         QUIET_MODE                           [Param] -Q: Quiet Mode, Mostly Used in Batch Mode
         AWR_TIME            8                [Param] -r: AWR Limit by Day
         TOP_AWR             3                [Param] -R: AWR Top AWR Report
         TOP_SEGMENTS        10               [Param] -s: AWR Top Segment Limits
         COLLECT_DG          1                [Param] -S: Collect DG Data
         ALERT_TIME          30               [Param] -t: Alert Log Limit by Day
         LSNR_TIME           30               [Param] -T: Listener Log Limit by Day
         DB_USER             sys              [Param] -u: DB Login - User
         DB_PSWD             oracle           [Param] -u: DB Login - Password
         DB_SERV                              [Param] -u: DB Login - Connect String
         ASM_USER            sys              [Param] -U: ASM Login - User
         ASM_PSWD            oracle           [Param] -U: ASM Login - Password
         ASM_SERV                             [Param] -U: ASM Login - Connect String
         TOP_WAITS           10               [Param] -w: AWR Top Event Limits
         RESULT_ZIP          1                [Param] -z: Use Zip File
       --------------------------------------------------------------------------------
       * Note: Variables with * means it can be query from DB or get with OS command,
               and normally user can not modify these variables.

--> b. Global Files
       This part of variables controls the directories and file of BTRobot.
       Do not modify this part.
       The meaning of them list as below :
       --------------------------------------------------------------------------------
         Name            Value                Description
         --------------- -------------------- -----------------------------------------
         DATA_DIR        data                 BTRobot's data directory
         CONFIG_DIR      conf                 BTRobot's configuration directory
         LIB_DIR         lib                  BTRobot's library directory
         RESULT_DIR      data                 Collection data directory, it different between each collections
         MODULE_DIR      module               External library used in batch collections
         DG_SCRIPT       DGRobot.pl           DG collection script
         NODE_SCRIPT     NodeRobot.pl         OS node collection script
         MAIN_SCRIPT     BTRobot.pl           BTRobot main collection script
         LIB_TOOLS       BTTools.pm           Tool library
         LIB_DBTOOL      DBTools.pm           DB tool library
         LIB_CONFIG      BTConfig.pm          BTRobot configuration library
         SERVER_CONFIG   DBServers.conf       DB Server Config in Batch Collection
         NOHUP_LOG       BTRobot_Nohup.log    Logfile for backgroup process when collect os data
         MONITOR_LOG     BTRobot_Monitor.log  Logfile for monitor process
         LOGFILE         BTRobot.log          Logfile for BTRobot main process
         WARN_LOGFILE    BTRobot_warn.log     Error/Warn logfile for BTRobot main process
         DBI_TRACE_FILE  BTRobot_DBI.trc      Logfile for DBI driver
       --------------------------------------------------------------------------------

--> c. OS Collection Modules
       This part of variables controls the os data collection by modules.
       The meaning of them list as below :
       --------------------------------------------------------------------------------
         Name         Value   Description
         ------------ ------- ---------------------------------------------------------
         osBasic      ENABLE  OS basic information collection, do not DISABLE it
         osAlert      ENABLE  DB alert logfile collection
         osCrontab    ENABLE  OS crontab collection, only valid for Linux/Unix
         osListener   ENABLE  DB listener logfile collection, include listener status and configurations
         osError      ENABLE  OS error log collection, only valid for AIX/HPUX/solaris
         osInstance   ENABLE  OS Extra-Instance collection
         osFS         ENABLE  OS file system usage collection
         osHosts      ENABLE  OS hosts configuration collection
         osMemory     ENABLE  OS memory usage collection
         osNIC        ENABLE  OS network configuration collection
         osOPatch     ENABLE  DB patch collection by opatch command
         osParameter  ENABLE  OS kernel parameters collection, only valid for Linux/Unix
       --------------------------------------------------------------------------------

--> d. Result Files
       This part of variables controls the format of each result file.
       For database data, the format is given by SQL query columns
       Each result items may have 5 attributes:
       --------------------------------------------------------------------------------
         a. FILE    : Result file name
         b. CLASS   : Result data type, it can be CT/OS/DB/DG/SUB
         c. DEFINE  : Valid in OS data items, it's the format of data lines
         d. SQL     : Valid in DB data items, for different version, it can be SQL/SQL_10/SQL_11/SQL_12
         e. STATUS  : Valid in DB data items, controls whether collect it or not
       --------------------------------------------------------------------------------
       * Note: User can change STATUS, but not to change other data.

--> e. Collection Status
       This part of variables controls the BTRobot collection status message.
       Do not modify this part.

--> f. Alert Capture Keywords
       This part of variables controls the keywords in DB alert logfile collection.
       Each item have to parts: Name and Expression(support simple regular expression).
       Examples list as below:
       --------------------------------------------------------------------------------
         Name              Expression
         ----------------  ---------------------------------------------------------
         CKPT_NOT_OK       Checkpoint\s+not\s+complete
         ARCH_REQUIRED     archival\s+required
         WARNING           warn
       --------------------------------------------------------------------------------
