PMDAORACLE(1)

okay bestie, welcome to pmdaoracle(1) — yes, we're in the General Commands Manual section, and this one is giving database observability in the best way 💅✨ let's get into it.

🎀 NAME 🎀

pmdaoracle — the Oracle database PMDA. that's the name, that's the whole thing 🫶

🦋 DESCRIPTION 🦋

pmdaoracle is a Performance Co-Pilot PMDA (that's a Performance Metrics Domain Agent, iykyk) and what it does is extract live performance data from a running Oracle database. literally pulling the real-time vibes straight out of your DB. no cap. 🔥

✨ INSTALLATION ✨

so pmdaoracle reads a configuration file, and it looks in these spots, in this exact order:

1. /etc/pcpdbi.conf
2. $PCP_PMDAS_DIR/oracle/oracle.conf
3. ./oracle.conf

that file can contain overridden values (Perl code, bestie, we're fancy) for the settings listed at the very 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 (the PMDA will run with the corresponding user id) [default: oracle]
• @sids — an array of $ORACLE_SID database identifiers [default: ('master')]

---

and look, to test your local settings there's a lil script provided that connects and disconnects from the database — it verifies the fundamental configuration is actually in place before you go any further 🧚

⚠️ BIG ONE: if the $PCP_PMDAS_DIR/oracle/connect.pl script cannot connect, do NOT proceed with installation of the PMDA, because it will be unsuccessful. correct your local settings first. periodt. 💀

once that's all set up, you can access the names and values for the oracle performance metrics by doing the following as root:

# cd $PCP_PMDAS_DIR/oracle
# ./Install

and to uninstall, this is what you do, also 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. so let them cook.

🔌 CONNECTION STATE 🔌

by default, pmdaoracle will aggressively attempt to maintain persistent connections to Oracle so it can give timely responses to its queries, and it will automatically re-connect if a connection drops. yes, it's clingy, and honestly? iconic behavior. 👑

but sometimes that's just not the vibe, 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 make sure pmdaoracle is not connected at shutdown, so you get 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, you can set the connection state to either up (1) or down (0). also, pminfo(1) can report on the current status of Oracle connections. bestie, look:

# 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 that PCP uses. on each installation, the file /etc/pcp.conf contains the local values for these variables. and 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). go read them, they're all slay 🫶

---

and that's the whole page, bestie!! this lil love letter comes to you from the fine folks at Performance Co-Pilot, a.k.a. PCP — that's the source/version tag riding on this very PMDAORACLE(1) page. go touch some metrics 💖✨🎀