NAME

       pmdaoracle - Oracle database PMDA

DESCRIPTION

       pmdaoracle  is  a  Performance  Co-Pilot  PMDA which extracts live performance data from a
       running Oracle database.

INSTALLATION

       pmdaoracle uses a configuration file from (in this order):
       •   /etc/pcpdbi.conf
       •   $PCP_PMDAS_DIR/oracle/oracle.conf
       •   ./oracle.conf

       This file can contain overridden values (Perl code) for the settings listed at  the  start
       of pmdaoracle.pl, for example:
       •   $username - username to connect to the database [default: 'SYSTEM']
       •   $password - password to connect to the database [default: 'manager']
       •   $host - host the database is running on [default: 'localhost']
       •   $port - port the database is listening on [default: '1521']
       •   $os_user  -  operating  system username (PMDA will run with the corresponding user id)
           [default: oracle]
       •   @sids - an array of $ORACLE_SID database identifiers [default: ('master')]

       In order to test your local settings, a simple script is provided that  will  connect  and
       disconnect  from  the  database  -  verifying fundamental configuration is in place before
       continuing on.  If the $PCP_PMDAS_DIR/oracle/connect.pl  script  cannot  connect,  do  not
       proceed  with  installation  of  the  PMDA as it will be unsuccessful.  Correct your local
       settings first.

       Once this is setup, you can access the names and values for the oracle performance metrics
       by doing the following as root:

             # cd $PCP_PMDAS_DIR/oracle
             # ./Install

       To uninstall, do the following as root:

             # cd $PCP_PMDAS_DIR/oracle
             # ./Remove

       pmdaoracle  is  launched by pmcd(1) and should never be executed directly. The Install and
       Remove scripts notify pmcd(1) when the agent is installed or removed.

CONNECTION STATE

       By default, pmdaoracle will aggressively attempt to  maintain  persistent  connections  to
       Oracle  to  ensure timely responses to its queries, and will automatically re-connect if a
       connection drops.

       However, in certain  circumstances  this  may  be  undesirable,  so  a  manual  pmStore(3)
       mechanism  is  provided  to explicitly control disconnecting and reconnecting to an Oracle
       instance.  This can be used, for example, to ensure that pmdaoracle is  not  connected  at
       shutdown, to ensure a clean Oracle shutdown process.

       The  pmstore  (1)  command  can be used to disconnect and reconnect.  Using the individual
       instances of the oracle.control.connected metric, one can  set  the  connection  state  to
       either  up  (1)  or down (0).  Additionally, pminfo(1) can report on the current status of
       Oracle connections.

            # pminfo ‐f oracle.control.connected

            oracle.control.connected
                inst [0 or "master"] value 1

            # pmstore oracle.control.connected 0
            oracle.control.connected inst [0 or "master"] old value=1 new value=0

FILES

       /etc/pcpdbi.conf
           configuration file for all PCP database monitors
       $PCP_PMDAS_DIR/oracle/oracle.conf
           configuration file for pmdaoracle
       $PCP_PMDAS_DIR/oracle/sample.conf
           example configuration file for pmdaoracle using $LD_LIBRARY_PATH
       $PCP_PMDAS_DIR/oracle/connect.pl
           configuration test script for Oracle database connectivity
       $PCP_PMDAS_DIR/oracle/Install
           installation script for the pmdaoracle agent
       $PCP_PMDAS_DIR/oracle/Remove
           undo installation script for the pmdaoracle agent
       $PCP_LOG_DIR/pmcd/oracle.log
           default log file for error messages from pmdaoracle

PCP ENVIRONMENT

       Environment variables with the prefix PCP_ are used to parameterize the file and directory
       names  used by PCP. On each installation, the file /etc/pcp.conf contains the local values
       for these variables.  The $PCP_CONF  variable  may  be  used  to  specify  an  alternative
       configuration file, as described in pcp.conf(5).

SEE ALSO

       PCPIntro(1), pmdadbping(1), pminfo(1), pmstore(1), DBI(3) and pmStore(3).