PMDABCC(1)

💖 PMDABCC — the BCC PMDA, bestie edition 💖

okay so you're looking at pmdabcc(1), a General Commands Manual page from the PCP crew. sit down, hydrate, and let's get into it ✨

---

🌸 NAME 🌸

pmdabcc — the BCC PMDA. that's the whole name. short, sweet, iconic.

---

✨ DESCRIPTION ✨

So. pmdabcc is a Performance Co-Pilot (PCP) Performance Metrics Domain Agent (PMDA) that pulls live performance data out of extended BPF (Berkeley Packet Filter) in-kernel programs, and it does it by using the BCC (BPF Compiler Collection) Python frontend. like, it's the bridge between your kernel's little BPF besties and your metrics. 💅

⚠️ heads up bestie, this one's deprecated. pmdabcc will be removed in a future release. the glow-up is to transition to its replacement, pmdabpf(1), instead. no cap.

pmdabcc loads and acts as a bridge for any number of configured, separate PCP BCC PMDA Python modules running BPF programs. and the good news? existing BCC Python tools and programs should be possible to be utilized with PCP BCC PMDA modules with reasonable effort. 🫶

See the BPF and BCC documentation for detailed description of both. (iykyk)

---

🎀 CONFIGURATION 🎀

pmdabcc reads a mandatory ini-style configuration file:

$PCP_PMDAS_DIR/bcc/bcc.conf

This file must contain a [pmda] section. the following PMDA options are available (their default values are shown in parenthesis), and options marked with asterisk (*) can be overridden in module-specific configuration sections:

• modules (unset) — the pmdabcc PMDA reads module-specific configuration for each module listed in the comma-separated list of modules. this one is mandatory, so like, don't skip it.
• prefix (bcc.) — by default, all metrics from the modules will appear under the bcc Performance Metrics Name Space (PMNS) tree. prefix (optional) can be used to change this generic prefix. 🌈
• process_refresh (0) — see below, bestie, there's a whole paragraph.
• module_failure_fatal (True) — a boolean value for module_failure_fatal (optional) that controls whether a module failing to compile should cause the whole PMDA to abort (this is the default) or to start up with possibly remaining functional modules. module configuration errors and internal errors (such as failing to register the provided PMNS metrics, see PMNS(5)) will always cause the PMDA to fail. no exceptions, periodt.

---

🧠 about that process option (yes, it's a whole thing)

Of particular note: the process option accepted by some modules evaluates the given PIDs and process names at PMDA/module initialization time and applies filtering for only those processes found at that stage. why tho? because the in-kernel BPF program is compiled at module initialization time and, even more importantly, they are often running at performance critical areas where it is not acceptable to do process name lookups each time a request is processed by the BPF program. 💀

So to allow modules to monitor named processes (say, process = java) even if they restart, the process_refresh should be set to a non-negative integer N to dynamically refresh monitored processes every N seconds. in case new processes matching the process filter have appeared, the currently running BPF is detached and a new BPF program with updated PID information is installed. and if no PIDs matching the filter are anymore present, the BPF program will be detached to avoid any needless overhead. main character efficiency, honestly. 👑

---

🦋 per-module sections

For each module listed in modules, a corresponding [module] section must be defined containing at least the following options:

• module — defines the actual Python module file name to be loaded during PMDA startup under the modules subdirectory of the PCP BCC PMDA installation.
• cluster — specifies the unique cluster ID (see PMNS(5)) for the metrics provided by the module under the PMNS path.

All modules accept but not necessarily use the boolean debug option.

Modules may also support additional module-specific configuration options — refer to the default configuration file for their supported options. 🍓

---

💜 INSTALLATION 💜

To install, the following must be done as root:

# cd $PCP_PMDAS_DIR/bcc
# ./Install

To uninstall, the following must be done as root:

# cd $PCP_PMDAS_DIR/bcc
# ./Remove

pmdabcc 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. let them handle it, bestie, they got this.

In case module_failure_fatal is set to False, the PMDA installation will be considered successful even if some or even all configured modules fail to load. in such cases, metric values provided by the failing modules will not be available. the pmdabcc agent log file (see below) will contain detailed information about activation of each module. 📝

Some modules will start providing values only after having collected data from related system activity. for instance, the tcpperpid module will not provide any values unless there are processes generating TCP traffic on the system. so like, no traffic, no metrics, that's just the vibe. 🙈

---

🧚 FILES 🧚

• $PCP_PMDAS_DIR/bcc/bcc.conf — configuration file for the pmdabcc agent
• $PCP_PMDAS_DIR/bcc/modules/*.{py,python} — PCP BCC PMDA Python modules available for the pmdabcc agent
• $PCP_PMDAS_DIR/bcc/Install — installation script for the pmdabcc agent
• $PCP_PMDAS_DIR/bcc/Remove — undo installation script for the pmdabcc agent
• $PCP_LOG_DIR/pmcd/bcc.log — default log file for messages from the pmdabcc agent

Note that the usual/default value for $PCP_PMDAS_DIR is /var/lib/pcp/pmdas and the default for $PCP_LOG_DIR is /var/log/pcp — but these settings are platform dependent. so like, check your own setup, don't just assume. 🌸

---

🌈 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), bcc(1), bpf(1), pmcd(1) and pmdabpf(1).

---

that's the whole page, bestie, you ate it 💅 and one last thing: this masterpiece came to you from Performance Co-Pilot, tagged PCP, filed under PMDABCC(1). go forth and monitor responsibly 🫶💖