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

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

SEE ALSO

       PCPIntro(1), bcc(1), bpf(1) and pmcd(1).

Performance Co-Pilot                                   PCP                                            PMDABCC(1)