Provided by: pcp_4.3.1-1_amd64 bug

NAME

       pmdabcc - BCC PMDA

DESCRIPTION

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

       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.

INSTALLATION

       pmdabcc reads a mandatory ini-style configuration file

           · $PCP_PMDAS_DIR/bcc/bcc.conf

       This file contains in its [pmda] section values for the following PMDA options:

           · modules
           · prefix
           · process_refresh
           · module_failure_fatal

       pmdabcc  reads module-specific configuration for each module listed in the comma-separated
       list of modules (mandatory).  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.  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 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.

       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  listed  module  a  corresponding [module] section must be defined containing at
       least the following options:

           · module
           · cluster

       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 cluster
       ID (see PMNS(5)) for the metrics provided by the module under the PMNS path.   Optionally,
       prefix  can  be defined to override the generic value described above.  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.

       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:

           # cd $PCP_PMDAS_DIR/bcc
           # ./Install

       To uninstall, do the following 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

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