PMDADB2(1)

📦 version 7.2.2, in arch rolling, fedora 43, fedora 44, ubuntu stonking

✨ PMDADB2 ✨ — ok bestie, it's the IBM Db2 database PMDA 🦋

aka the pmdadb2 manual page, and yes it's from section 1 of the General Commands Manual, iykyk 💅

NAME

pmdadb2 — it's the IBM Db2 database PMDA 🎀

DESCRIPTION

okay so pmdadb2 is a Performance Co-Pilot (PCP) Performance Metrics Domain Agent (PMDA) and what it does is literally pull live performance data out of a running IBM Db2 database server using the Db2 monitoring table functions, aka the MON_GET_* ones 🌸

The metrics are organised into these groups, and no we are not skipping any of them, every single one is getting its moment 👑

db2.instance — instance-level identity metrics, coming at you from ENV_GET_INSTANCE_INFO. It covers the instance name, the full service level (that's the version) string, and the operating platform. Heads up bestie: these are PM_SEM_DISCRETE metrics, so they get logged once at recording start and then only whenever they change. Not every second, they're not extra like that 💅
db2.database — database-wide aggregate counters from MON_GET_DATABASE. Covering transactions, row operations, sort activity, locking, package cache efficiency, and direct I/O. The instance domain has one entry per monitored database name, periodt.
db2.bufferpool — per-buffer-pool counters from MON_GET_BUFFERPOOL, covering logical and physical reads and writes for data, index, and column-organised pages, plus pool read/write times and unread prefetch pages. Instance names look like dbname::bpname 🫶
db2.table — per-table counters from MON_GET_TABLE, covering row operations, lock activity, overflow accesses, and full-table scans. System tables (that's anything with the schema prefix SYS) are excluded — not invited to the party, sorry. Instance names are dbname::tabschema.tabname.
db2.workload — per-workload counters from MON_GET_WORKLOAD, covering row operations, CPU time, and transaction counts. Instance names are dbname::workload_name.
db2.tablespace — per-tablespace I/O counters from MON_GET_TABLESPACE, covering buffer pool and direct read/write operations and times. Instance names are dbname::tablespace_name.
db2.connection — per-connection counters from MON_GET_CONNECTION, covering CPU time, row operations, lock activity, and transaction counts. Instance names are dbname::appname::handle.
db2.latch — per-latch-type extended wait statistics from MON_GET_LATCH, covering cumulative wait time and event count. Important: only latch types that have experienced at least one extended wait event even show up in the instance domain. If a latch has never waited, it's simply not there, main character energy only 😌 Instance names are dbname::latch_name.
db2.log — transaction log I/O counters from MON_GET_TRANSACTION_LOG, covering log write and read operations, physical I/O counts, buffer-full events, and current used and available log space. The instance domain has one entry per monitored database name.
db2.pkg_cache — package cache aggregate counters from MON_GET_PKG_CACHE_STMT, summarising the entire statement cache with no per-statement instance domain at all. It's giving: cached statement count, total executions, CPU time, rows read, sort operations, and sort overflows. And yep — the instance domain has one entry per monitored database name. Slay 💖

CONFIGURATION

First things first bestie: pmdadb2 requires you to install the ibm_db Python package, because that's the thing that provides the IBM Db2 driver for Python 🐍

Then, pmdadb2 reads a mandatory ini-style configuration file:

$PCP_SYSCONF_DIR/db2/db2.conf

This file has two sections. (Yes, we're reading that straight off the page, don't come for me 🙈)

[connection] — how to reach the Db2 server

Default values are shown in parentheses, no cap:

hostname (localhost) — hostname or IP address of the Db2 instance.
port (50000) — TCP port number of the Db2 instance listener.
timeout (5) — connection timeout, in seconds.

[databases] — which databases on the instance to monitor

names — space-separated list of Db2 database names to monitor. All of these databases have to be reachable at the configured hostname and port using the same credentials, that's the vibe check. The database name shows up as the instance name for db2.database.*, db2.log.* and db2.pkg_cache.* metrics, and it also becomes the dbname:: prefix in every per-object instance domain (buffer pools, tables, tablespaces, workloads, connections, latches) 💫

[authentication] — the Db2 user credentials

username — the Db2 username to authenticate as. This user must have EXECUTE privilege on the MON_GET_* table functions, plus DATAACCESS or the appropriate MON_* authorities on the target database. No shortcuts here, the privileges are the privileges 🔐
password — the password for the above username.

INSTALLATION

To install, all of this has to be done as root:

# cd $PCP_PMDAS_DIR/db2
# ./Install

To uninstall, also as root:

# cd $PCP_PMDAS_DIR/db2
# ./Remove

pmdadb2 is launched by pmcd(1) and should never be executed directly. Like genuinely, do not run it yourself, that's not the move 🙅

The Install and Remove scripts notify pmcd(1) when the agent is installed or removed, so it always knows what's going on 💅

Oh and also — pmdadb2 will automatically attempt to reconnect to the Db2 server if the connection is lost. Resilient queen behavior honestly 👑

FILES

$PCP_SYSCONF_DIR/db2/db2.conf — configuration file for the pmdadb2 agent
$PCP_PMDAS_DIR/db2/Install — installation script for the pmdadb2 agent
$PCP_PMDAS_DIR/db2/Remove — undo installation script for the pmdadb2 agent
$PCP_LOG_DIR/pmcd/db2.log — default log file for messages from the pmdadb2 agent

Note that the usual/default value for $PCP_SYSCONF_DIR is /etc/pcp, the default for $PCP_PMDAS_DIR is /var/lib/pcp/pmdas and the default for $PCP_LOG_DIR is /var/log/pcp — but bestie, these settings are platform dependent, so check before you assume 🌈

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 if you need a different config file entirely, the $PCP_CONF variable can be used to specify an alternative one, exactly as described in pcp.conf(5) 🌸