pmdabcc(1) — Linux manual page


PMDABCC(1)                 General Commands Manual                PMDABCC(1)

NAME         top

       pmdabcc - BCC PMDA

DESCRIPTION         top

       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.


       pmdabcc reads a mandatory ini-style configuration file:


       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

       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

       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

INSTALLATION         top

       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         top

            configuration file for the pmdabcc agent

            PCP BCC PMDA Python modules available for the pmdabcc agent

            installation script for the pmdabcc agent

            undo installation script for the pmdabcc agent

            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.


       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         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2020-08-13.  (At that time, the date of the most recent commit that
       was found in the repository was 2020-08-11.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot                 PCP                          PMDABCC(1)