pmdabcc - BCC PMDA
pmdabcc is a Performance Co-Pilot (PCP) Performance Metrics Domain Agent
(PMDA) which extracts live performance data from extended BPF (Berkeley Packet
Filter) in-kernel programs by using BCC (BPF Compiler Collection) Python
frontend.
pmdabcc loads and acts as a bridge for any number of configured, separate
PCP BCC PMDA Python modules running BPF programs. 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.
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), 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
(mandatory).
- 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.
- module_failure_fatal (True)
- A boolean value for module_failure_fatal (optional)
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.
Of particular note, the
process option accepted by some modules evalutes
the given PIDs and process names at PMDA/module initialization time and apply
filtering for only those processes found at that stage. This is due to fact
that 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. 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 detach to avoid any
needless overhead).
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.
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.
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.
- $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.
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).
PCPIntro(1),
bcc(1),
bpf(1) and
pmcd(1).