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