
[1] 简介
================================================================================
    Bethune 数据采集工具（BTRobot）采用 Perl 语言编写。在 Windows 环境中使用 Oracle 自
    带的 perl 程序执行，Linux/Unix 程序均可使用自带的 perl 程序执行。

    在采集过程中，会用到以下三种数据采集方式：
      a. 调用命令：获取操作系统相关的数据
      b. 读取文件：获取操作系统配置信息，以及日志数据
      c. DBI驱动：查询数据库中的相关数据

    对于 BTRobot 来说，有以下几种目录和文件：
      a. conf          : 采集程序的配置文件目录
      b. data          : 采集程序的结果集目录
      c. lib           : 采集程序的相关模块及脚本目录
      d. module        : 批量采集模式下引用的外部模块
      e. runMe.pl      : 采集的入口调度程序
      f. ReadMe_CN.txt : 中文版的采集程序帮助与说明文档
      g. ReadMe_EN.txt : 英文版的采集程序帮助与说明文档


[2] 参数选项
=======================================================================================
    参数  说明                                       默认值
    ---- ------------------------------------------ ------------
     -B  指定 AWR 繁忙时段（范围：0 ~ 23）             0-23
         格式: 8-18 或 9,10,15,16 或 9-12,14-18
     -c  指定字符集编码，支持 GBK 和 UTF8
         格式: O=GBK,A=GBK,L=GBK
              O 为 Oracle 数据库编码
              A 为告警日志编码
              L 为监听日志编码
     -d  指定需要跳过的 OS 采集模块                  (例如: osCrontab,osListener)
         格式: osCrontab,osListener
         说明: 跳过指定的 OS 采集模块
     -e  指定主机错误日志采集天数（AIX/SunOS/HPUX）    30
     -h  查看采集程序的帮助信息
     -i  指定 ASM 实例的 SID                         NONE
     -L  指定联机日志历史记录的采集天数                 30
     -M  批量采集时，指定 conf 目录中服务器参数文件     DBServers.conf
     -o  指定 ASM 的 Home 目录                       NONE
     -p  指定主采集节点的监听端口号                    12345
     -Q  静默模式，主要配合多服务器批量采集
     -r  指定 AWR 相关数据的采集天数                   8
     -R  指定 AWR 报告的采集数量（按 DB Time 取 Top）  3
     -s  指定 Top Segment 的采集数量                  10
     -S  不采集 DG 数据
     -t  指定告警日志的采集天数                        30
     -T  指定监听日志的采集天数                        30
     -u  指定 Oracle 实例的登录方式                   sys/oracle
     -U  指定 ASM 实例的登录方式                      sys/oracle
     -v  查看采集程序的版本号
     -w  指定每个快照中 Top Event 的采集数量           10
     -z  不自动打包结果集


[3] 使用方法
=======================================================================================
--> 首先，我们强烈建议用户通读整篇帮助文档
    * 注意：以下目录可能与您的实际环境略有不同
    -----------------------------------------------------------------------------------
      cd /home/oracle/BTRobot_v2.4.0
      perl runMe.pl -h

--> 对于 Window 平台
    * 注意：perl.exe 程序的目录可能与您的实际环境略有不同
    -----------------------------------------------------------------------------------
      SET ORACLE_HOME=C:\oracle\product\10.2.0\db_1
      SET ORACLE_SID=WINDB
      SET PATH=%ORACLE_HOME%\bin;%PATH%         # 添加 Oracle 执行程序目录
      SET PATH=%ORACLE_HOME%\perl\bin;%PATH%    # 添加 Oracle 自带的 Perl 程序目录
      where perl             # 确认 Perl 程序是否存在
      sqlplus / as sysdba    # 检查数据库是否可以以系统认证登录，否则您需要使用 -u 选项
      cd C:\BTRobot_v2.4.0
      perl runMe.pl

--> 对于 Linux/Unix 平台
    * 注意：以下目录可能与您的实际环境略有不同
    -----------------------------------------------------------------------------------
      which perl             # 确认 Perl 程序是否存在
      sqlplus / as sysdba    # 检查数据库是否可以以系统认证登录，否则您需要使用 -u 选项
      cd /home/oracle/BTRobot_v2.4.0
      perl runMe.pl

 --> 批量采集
     * 注意：该模式仅在支持 SSH 协议（SCP 可用）的 Linux/Unix 环境下可用
            以下目录可能与您的实际环境略有不同
            在一台可以自由安装 Perl 模块的服务器，且能 SSH 连通所有待采集库操作采集
     -----------------------------------------------------------------------------------
       su - root                              # 需要 root 用户安装 Perl 模块
       which perl                             # 确认 Perl 程序是否存在
       cd /home/oracle/BTRobot_v2.0.0/module
       # 安装必须的 Perl 模块
       tar -zxvf IO-Tty-1.12.tar.gz           # 安装模块 IO-TTY/PTY
       cd IO-Tty-1.12
       perl Makefile.PL
       make
       make test
       make install
       tar -zxvf Expect-1.32.tar.gz           # 安装模块 Expect
       cd Expect-1.32
       perl Makefile.PL
       make
       make test
       make install
       tar -zxvf Net-SSH-Expect-1.09.tar.gz   # 安装模块 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   # 安装模块 Net-SCP-Expect
       cd Net-SCP-Expect-0.12
       perl Makefile.PL
       make
       make test
       make install
       # 编写 DB 服务器的配置文件，详细说明参考： conf/DBServers.conf
       vi conf/DBServers.conf
       # 以批量采集模式运行采集程序
       perl runMe.pl -M


[4] 交互处理
=======================================================================================
--> a. RAC 环境无用户互信
    通常，RAC环境中的所有节点的安装用户之间均会配置用户 SSH 互信。在这种情况下，BTRobot 采集程序能够在
    一个节点采集到集群中所有节点的数据。如果用户 SSH 互信没有配置，那么会有如下提示：
    -----------------------------------------------------------------------------------
       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)
       ====>
    -----------------------------------------------------------------------------------
    我们建议使用【监听模式】采集远程节点的数据
    【密码模式】：输入远程节点的 Oracle 安装用户的密码，以此登录远程节点并采集数据
    【监听模式】：手动在远程节点执行一条采集命令，用于远程数据的采集

--> b. 等待接收节点数据
    在【a】情况中，在采集远程节点数据时，以下提示可能会出现：
    -----------------------------------------------------------------------------------
       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 ]--------------------------------
    -----------------------------------------------------------------------------------
    当看到这个提示的时候，当前采集程序会暂停，用户需要拷贝提示中完整的 perl 命令，并在远程节点执行
    注意：在完整命令中，第二行的 IP 地址（当前执行采集程序的节点 IP）如果有误的话，可能需要修改

--> c. 等等接收 DG 数据
    但采集程序发现 DG 环境时，以下提示会出现：
    -----------------------------------------------------------------------------------
       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 ]--------------------------------
    -----------------------------------------------------------------------------------
    当看到这个提示的时候，当前采集程序会暂停，用户需要拷贝提示中完整的 perl 命令，并在远程节点执行
    注意：在完整命令中，第二行的 IP 地址（当前执行采集程序的节点 IP）如果有误的话，可能需要修改


[5] 采集配置
    在【conf】目录中存放着一些采集程序的配置文件。
=======================================================================================
--> 配置【BTConfig.pm】
    配置文件【BTConfig.pm】存储着 BTRobot 采集程序的大部分配置参数。目前该配置文件中有 5 个部分
    -----------------------------------------------------------------------------------
      a. Global Parameters       -- 全局配置参数
      b. Global Files            -- 全局文件，不要修改这部分内容
      c. OS Collection Modules   -- 主机层的采集模块
      d. Result Files            -- 结果集文件相关的配置
      e. Collection Status       -- 采集项的状态信息，不要修改这部分内容
    -----------------------------------------------------------------------------------

--> a. Global Parameters
       这部分变量控制着 BTRobot 采集数据时的行为方式，其含义如下：
       --------------------------------------------------------------------------------
         名称                参数值            描述
         ------------------- ---------------- -----------------------------------------
         SCRIPT_VERSION      2.4.0            [Var  ] 当前脚本的版本
         ------------------- ---------------- -----------------------------------------
         ALERT_KEEP          50               [Var  ] 告警日志中报错信息前后分别保留的上下文行数
         ALT_IGNORE          <Not_List_Here>  [Var  ] 告警日志中，忽略的报错类型
         CPU_MIN_IDLE        10               [Var  ] CPU Idle 监控阈值，低于此值会自动终止采集, -1 即为不监控
         DIR_MIN_SIZE        100              [Var  ] 采集结果目录剩余空间（单位：MB）监控阈值，低于此值会自动终止采集, -1 即为不监控
         EVENT_FILTER        <Not_List_Here>  [Var  ] 等待事件采集列表，列表中等待事件强制采集
         ORACLE_HOME         NONE             [Var  ] 其值来源于操作系统环境变量 ORACLE_HOME
         ORACLE_SID          NONE             [Var  ] 其值来源于操作系统环境变量 ORACLE_SID
         PRINT_PROCESS       1                [Var  ] 打印第一次的进程信息，用于采集相关的问题诊断
         REMOTE_LOGIN        EQUAL            [Var  ] 远程采集方式，在 RAC 环境中会在交互模式中设定其值
         SKIP_STEP           0                [Var  ] 跳过部分采集项目，目前仅支持跳过 DG 数据
         SM_INTERVAL         5                [Var  ] 程序自我监控的间隔（单位：秒），0 表示不进行自我监控
         SQL_BATCH_SIZE      200              [Var  ] 采集 SQL 相关数据时的批次大小
         SYSSTAT_FILTER      <Not_List_Here>  [Var  ] 采集数据中的 AWR Sysstat 列表
         TARGET_CHARSET      UTF8             [Var  ] 结果集文件的编码方式，不要修改此参数
         TMOD_FILTER         <Not_List_Here>  [Var  ] 采集数据中的 AWR Time Model 列表
         TOP_SQL             32               [Var  ] 采集的 AWR SQL Stat 中的 SQL 最少数量
         ------------------- ---------------- -----------------------------------------
         ASM_DIAG            NONE             [Var *] ASM 实例的诊断日志的目录
         CLT_TIME                             [Var *] 数据包的采集时间
         DB_NAME                              [Var *] 数据库名称
         DB_ROLE                              [Var *] 数据库角色
         DB_VERSION                           [Var *] 数据库版本
         DBID                0                [Var *] 数据库 DBID
         EXTINST_TYPE        DG               [Var *] 非当前采集库的实例的类型
         GLOBAL_ERROR                         [Var *] 全局错误信息
         HOSTIP              127.0.0.1        [Var *] 当前节点的 IP 地址
         HOSTNAME            HOSTNAME         [Var *] 操作系统名称
         INST_COUNT          0                [Var *] 实例数量
         INST_TYPE           DB               [Var *] 实例类型（DB/ASM）
         INSTANCE_LIST                        [Var *] 采集主机中的其他运行实例时的实例列表
         LISTEN_NODE         NONE             [Var *] 采集程序的监听节点
         MIN_SNAP            0                [Var *] AWR 相关数据采集的最小 Snapshot ID
         MONITOR_PID         1                [Var *] 自我监控的进程 ID
         OBJ_SCHEMA                           [Var *] 采集 AWR SQL 中涉及到的对象时，对象的属主
         OS_TYPE             Linux            [Var *] 主机类型
         OS_USER             oracle           [Var *] 主机登录用户
         PATH                                 [Var *] 主机 PATH 变量的路径，来源于主机环境变量 PATH
         SQL_LIST                             [Var *] 采集 AWR SQL 中涉及到的对象时，当前批次采集的对象列表
         TRACE_LIMIT         51200            [Var *] 告警日志采集时，trace 文件的开头和结尾的文件大小限制
         UNIQUE_NAME                          [Var *] 数据库唯一名
         ------------------- ---------------- -----------------------------------------
         DB_CHARSET          NONE             [Param] -c: 数据库字符集
         OS_CHARSET          NONE             [Param] -c: 主机字符集
         ALT_CHARSET         NONE             [Param] -c: 告警日志字符集
         LSN_CHARSET         NONE             [Param] -c: 监听日志字符集
         OSERR_TIME          30               [Param] -e: 主机日志采集天数
         ASM_SID             NONE             [Param] -i: ASM 实例名
         LOG_LIMIT           30               [Param] -L: 数据库联机日志历史记录采集天数
         ASM_HOME            NONE             [Param] -o: ASM Home 目录
         LISTEN_PORT         12345            [Param] -p: 采集程序的监听目录
         QUIET_MODE                           [Param] -Q: 静默模式，通常与批量采集配合使用
         AWR_TIME            8                [Param] -r: AWR 相关数据的采集天数
         TOP_AWR             3                [Param] -R: AWR 报告的采集数量（按照 DB Time 取 Top）
         TOP_SEGMENTS        10               [Param] -s: Top 段的采集数量
         COLLECT_DG          1                [Param] -S: 是否采集 DG 数据
         ALERT_TIME          30               [Param] -t: 告警日志的采集天数
         LSNR_TIME           30               [Param] -T: 监听日志的采集天数
         DB_USER             sys              [Param] -u: 数据库登录 - 用户名
         DB_PSWD             oracle           [Param] -u: 数据库登录 - 密码
         DB_SERV                              [Param] -u: 数据库登录 - 连接串
         ASM_USER            sys              [Param] -U: ASM 登录 - 用户名
         ASM_PSWD            oracle           [Param] -U: ASM 登录 - 密码
         ASM_SERV                             [Param] -U: ASM 登录 - 连接串
         TOP_WAITS           10               [Param] -w: AWR Top 等待事件的采集数量
         RESULT_ZIP          1                [Param] -z: 是否自动压缩结果集目录
       --------------------------------------------------------------------------------
       注意：带【*】表示该变量为自动获取型的（来源于数据库或主机命令），用户不能执行修改

--> b. Global Files
       这部分变量控制采集程序的相关文件及目录位置，用户请不要自行修改这部分的配置。
       其含义如下：
       --------------------------------------------------------------------------------
         名称            参数值                描述
         --------------- -------------------- -----------------------------------------
         DATA_DIR        data                 结果集目录
         CONFIG_DIR      conf                 配置文件目录
         LIB_DIR         lib                  相关依赖脚本和模块的目录
         RESULT_DIR      data                 当前采集的结果集目录
         MODULE_DIR      module               批量采集时引用的外部模块
         DG_SCRIPT       DGRobot.pl           DG 数据采集脚本
         NODE_SCRIPT     NodeRobot.pl         主机数据采集脚本
         MAIN_SCRIPT     BTRobot.pl           主采集脚本
         LIB_TOOLS       BTTools.pm           工具类的函数模块
         LIB_DBTOOL      DBTools.pm           DB 操作相关的函数模块
         LIB_CONFIG      BTConfig.pm          采集程序的配置文件
         SERVER_CONFIG   DBServers.conf       批量采集时的服务器配置信息
         NOHUP_LOG       BTRobot_Nohup.log    后台运行的命令或脚本的日志输出
         MONITOR_LOG     BTRobot_Monitor.log  朱采集节点的自我监控日志
         LOGFILE         BTRobot.log          采集程序的详细日志
         WARN_LOGFILE    BTRobot_warn.log     命令或程序异常的日志信息
         DBI_TRACE_FILE  BTRobot_DBI.trc      数据库 DBI 驱动的日志
       --------------------------------------------------------------------------------

--> c. OS Collection Modules
       这部分变量控制主机数据采集模块。
       其含义如下：
       --------------------------------------------------------------------------------
         Name         Value   Description
         ------------ ------- ---------------------------------------------------------
         osBasic      ENABLE  OS 基础配置信息的采集，不要禁用此采集项
         osAlert      ENABLE  数据库告警日志采集模块
         osCrontab    ENABLE  Linux/Unix 平台中主机定时任务的采集
         osListener   ENABLE  数据库监听相关数据的采集模块
         osError      ENABLE  主机日志采集模块，目前只在 AIX/HPUX/solaris 平台有效
         osInstance   ENABLE  主机上运行的其他实例的基本信息采集模块
         osFS         ENABLE  主机文件系统使用情况的采集模块
         osHosts      ENABLE  主机 hosts 配置采集模块
         osMemory     ENABLE  主机内存使用情况的采集模块
         osNIC        ENABLE  主机网络配置信息的采集模块
         osOPatch     ENABLE  数据库补丁（来源于 opatch 命令）采集模块
         osParameter  ENABLE  Linux/Unix 平台中的内核参数采集模块
       --------------------------------------------------------------------------------

--> d. Result Files
       这部分变量控制每个采集项的数据，对于数据库相关的采集项，数据定义来源于 SQL 查询列
       每个采集项可能都有以下 5 个属性：
       --------------------------------------------------------------------------------
         a. FILE    : 采集结果所存储的文件名
         b. CLASS   : 采集项的类别（CT/OS/DB/DG/SUB）
         c. DEFINE  : 采集项的结果定义，一般用于主机相关采集项，少量数据库采集项也可能会用到
         d. SQL     : 数据库相关采集项的采集 SQL，根据版本不同，可分为：SQL/SQL_10/SQL_11/SQL_12
         e. STATUS  : 非 OS 类别的采集项中有效，控制是否采集该采集项的数据
       --------------------------------------------------------------------------------
       注意：用户一般可以修改状态，但在无指导情况下，请不要修改其他数据

--> e. Collection Status
       这部分变量控制各个采集项的采集状态信息，用于无法修改这部分数据。

--> f. Alert Capture Keywords
       这部分变量控制着告警日志采集时，需要捕获的关键字信息。每一项关键字信息分为两个部分：
       名称和采集表达式（支持简单的正则表达式规则）。
       示例如下：
       --------------------------------------------------------------------------------
         名称              采集表达式
         ----------------  ---------------------------------------------------------
         CKPT_NOT_OK       Checkpoint\s+not\s+complete
         ARCH_REQUIRED     archival\s+required
         WARNING           warn
       --------------------------------------------------------------------------------
