# pmdabcc

## NAME



           **pmdabcc** - BCC PMDA
    


## DESCRIPTION



           **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.
    


## 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), 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
           evaluates 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.
    


## 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.
    
           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.
    


## 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.
    


## 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).
    


* * *