'\"macro stdmacro .\" .\" Copyright (C) 2017-2018 Marko Myllynen .\" .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2 of the License, or .\" (at your option) any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .TH PMDABCC 1 "PCP" "Performance Co-Pilot" .SH NAME \f3pmdabcc\f1 \- BCC PMDA .SH DESCRIPTION \fBpmdabcc\fP is a 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. .PP \fBpmdabcc\fP 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. .PP See the BPF and BCC documentation for detailed description of both. .PP .SH INSTALLATION \fBpmdabcc\fP reads a mandatory ini-style configuration file .IP .PD 0 .RS +4 .IP \(bu 2 .I \f(CW$PCP_PMDAS_DIR\fP/bcc/bcc.conf .RE .PD .PP This file contains in its \fB[pmda]\fP section values for the following PMDA options: .IP .PD 0 .RS +4 .IP \(bu 2 modules .IP \(bu prefix .IP \(bu process_refresh .IP \(bu module_failure_fatal .RE .PD .PP \fBpmdabcc\fP reads module-specific configuration for each module listed in the comma-separated list of \fBmodules\fP (mandatory). By default, all metrics from the modules will appear under the \fIbcc\fP Performance Metrics Name Space (PMNS) tree, \fBprefix\fP (optional) can be used to change this generic prefix. A boolean value for \fBmodule_failure_fatal\fP (optional) controls whether a module failing to compile should cause the whole PMDA to abort (this is the default) or to start up with any possibly functional modules. Module configuration errors and internal errors (such as failing to register the provided PMNS metrics) will always cause the PMDA to fail. .PP Of particular note, the \fBprocess\fP 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, \fBprocess = java\fP) even if they restart the \fBprocess_refresh\fP should be set to a non-negative integer \fIN\fP to dynamically refresh monitored processes every \fIN\fP 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). .PP For each listed module a corresponding \fB[module]\fP section must be defined containing at least the following options: .IP .PD 0 .RS +4 .IP \(bu 2 module .IP \(bu cluster .RE .PD .PP \fBmodule\fP defines the actual Python module file name to be loaded during PMDA startup under the \fImodules\fP subdirectory of the PCP BCC PMDA installation. \fBcluster\fP specifies the cluster ID (see \fBPMNS\fP(5)) for the metrics provided by the module under the PMNS path. Optionally, \fBprefix\fP can be defined to override the generic value described above. All modules accept but not necessarily use the boolean \fBdebug\fP option. .PP Modules may also support additional module-specific configuration options, refer to the default configuration file for their supported options. .PP Once the needed setup is ready, you can install the PMDA to load the configured modules and the BPF programs they utilize. To install, do the following as root: .sp 1 .RS +4 .ft B .nf # cd $PCP_PMDAS_DIR/bcc # ./Install .fi .ft P .RE .sp 1 To uninstall, do the following as root: .sp 1 .RS +4 .ft B .nf # cd $PCP_PMDAS_DIR/bcc # ./Remove .fi .ft P .RE .sp 1 \fBpmdabcc\fP is launched by \fBpmcd\fP(1) and should never be executed directly. The Install and Remove scripts notify \fBpmcd\fP(1) when the agent is installed or removed. .PP In case \fBmodule_failure_fatal\fP is set to \fBfalse\fP, 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 \fBpmdabcc\fP agent log file (see below) will contain detailed information about activation of each module. .PP Some modules will start providing values only after having collected data from related system activity. For instance, the \fBtcpperpid\fP module will not provide any values unless there are processes generating TCP traffic on the system. .SH FILES .TP .I \f(CW$PCP_PMDAS_DIR\fP/bcc/bcc.conf configuration file for the \fBpmdabcc\fP agent .TP .I \f(CW$PCP_PMDAS_DIR\fP/bcc/modules/*.{py,python} PCP BCC PMDA Python modules available for the \fBpmdabcc\fP agent .TP .I \f(CW$PCP_PMDAS_DIR\fP/bcc/Install installation script for the \fBpmdabcc\fP agent .TP .I \f(CW$PCP_PMDAS_DIR\fP/bcc/Remove\fP undo installation script for the \fBpmdabcc\fP agent .TP .I \f(CW$PCP_LOG_DIR\fP/pmcd/bcc.log default log file for messages from the \fBpmdabcc\fP agent .SH PCP ENVIRONMENT Environment variables with the prefix \fBPCP_\fP are used to parameterize the file and directory names used by PCP. On each installation, the file \fB/etc/pcp.conf\fP contains the local values for these variables. The \fB$PCP_CONF\fP variable may be used to specify an alternative configuration file, as described in \fBpcp.conf\fP(5). .SH SEE ALSO .BR PCPIntro (1), .BR bcc (1), .BR bpf (1), and .BR pmcd (1).