1PMDABCC(1)                  General Commands Manual                 PMDABCC(1)
2
3
4

NAME

6       pmdabcc - BCC PMDA
7

DESCRIPTION

9       pmdabcc  is  a  Performance  Co-Pilot  (PCP) Performance Metrics Domain
10       Agent (PMDA) which extracts live performance  data  from  extended  BPF
11       (Berkeley  Packet Filter) in-kernel programs by using BCC (BPF Compiler
12       Collection) Python frontend.
13
14       pmdabcc loads and acts as a bridge for any number of configured,  sepa‐
15       rate  PCP  BCC  PMDA Python modules running BPF programs.  Existing BCC
16       Python tools and programs should be possible to be  utilized  with  PCP
17       BCC PMDA modules with reasonable effort.
18
19       See the BPF and BCC documentation for detailed description of both.
20

CONFIGURATION

22       pmdabcc reads a mandatory ini-style configuration file:
23
24              $PCP_PMDAS_DIR/bcc/bcc.conf
25
26       This  file  must  contain a [pmda] section.  The following PMDA options
27       are available (their default values are shown in parenthesis),  options
28       marked  with asterisk (*) can be overridden in module-specific configu‐
29       ration sections:
30
31       modules (unset)
32                      The pmdabcc PMDA reads module-specific configuration for
33                      each  module  listed in the comma-separated list of mod‐
34                      ules (mandatory).
35
36       prefix (bcc.) *
37                      By default, all metrics from  the  modules  will  appear
38                      under  the  bcc  Performance  Metrics  Name Space (PMNS)
39                      tree, prefix (optional)  can  be  used  to  change  this
40                      generic prefix.
41
42       process_refresh (0)
43                      See below.
44
45       module_failure_fatal (True)
46                      A boolean value for module_failure_fatal (optional) con‐
47                      trols whether a module failing to compile  should  cause
48                      the  whole  PMDA  to  abort  (this is the default) or to
49                      start up with  possibly  remaining  functional  modules.
50                      Module configuration errors and internal errors (such as
51                      failing to  register  the  provided  PMNS  metrics,  see
52                      PMNS(5)) will always cause the PMDA to fail.
53
54       Of  particular  note, the process option accepted by some modules eval‐
55       utes the given PIDs and process  names  at  PMDA/module  initialization
56       time  and apply filtering for only those processes found at that stage.
57       This is due to fact that the in-kernel BPF program is compiled at  mod‐
58       ule initialization time and, even more importantly, they are often run‐
59       ning at performance critical areas where it is  not  acceptable  to  do
60       process  name  lookups each time a request is processed by the BPF pro‐
61       gram.  To allow modules to monitor  named  processes  (say,  process  =
62       java)  even if they restart the process_refresh should be set to a non-
63       negative integer N to dynamically refresh monitored processes  every  N
64       seconds.   In  case  new  processes  matching  the  process filter have
65       appeared, the currently running BPF is detached and a new  BPF  program
66       with  updated PID information is installed (and if no PIDs matching the
67       filter are anymore present, the BPF program will be detach to avoid any
68       needless overhead).
69
70       For each module listed in modules a corresponding [module] section must
71       be defined containing at least the following options:
72
73       module         Defines the actual Python module file name to be  loaded
74                      during  PMDA  startup  under the modules subdirectory of
75                      the PCP BCC PMDA installation.
76
77       cluster        Specifies the unique cluster ID (see  PMNS(5))  for  the
78                      metrics provided by the module under the PMNS path.
79
80       All modules accept but not necessarily use the boolean debug option.
81
82       Modules  may  also  support  additional  module-specific  configuration
83       options, refer to the default configuration file  for  their  supported
84       options.
85

INSTALLATION

87       To install, the following must be done as root:
88
89           # cd $PCP_PMDAS_DIR/bcc
90           # ./Install
91
92       To uninstall, the following must be done as root:
93
94           # cd $PCP_PMDAS_DIR/bcc
95           # ./Remove
96
97       pmdabcc  is  launched by pmcd(1) and should never be executed directly.
98       The Install and  Remove  scripts  notify  pmcd(1)  when  the  agent  is
99       installed or removed.
100
101       In  case  module_failure_fatal  is  set to False, the PMDA installation
102       will be considered successful even if some or even all configured  mod‐
103       ules  fail to load, in such cases metric values provided by the failing
104       modules will not be available.  The pmdabcc agent log file (see  below)
105       will contain detailed information about activation of each module.
106
107       Some  modules  will  start providing values only after having collected
108       data from related system activity.  For instance, the tcpperpid  module
109       will  not  provide any values unless there are processes generating TCP
110       traffic on the system.
111

FILES

113       $PCP_PMDAS_DIR/bcc/bcc.conf
114            configuration file for the pmdabcc agent
115
116       $PCP_PMDAS_DIR/bcc/modules/*.{py,python}
117            PCP BCC PMDA Python modules available for the pmdabcc agent
118
119       $PCP_PMDAS_DIR/bcc/Install
120            installation script for the pmdabcc agent
121
122       $PCP_PMDAS_DIR/bcc/Remove
123            undo installation script for the pmdabcc agent
124
125       $PCP_LOG_DIR/pmcd/bcc.log
126            default log file for messages from the pmdabcc agent
127
128       Note   that   the   usual/default   value   for    $PCP_PMDAS_DIR    is
129       /var/lib/pcp/pmdas and the default for $PCP_LOG_DIR is /var/log/pcp but
130       these settings are platform dependent.
131

PCP ENVIRONMENT

133       Environment variables with the prefix PCP_ are used to parameterize the
134       file  and  directory names used by PCP.  On each installation, the file
135       /etc/pcp.conf contains the  local  values  for  these  variables.   The
136       $PCP_CONF  variable may be used to specify an alternative configuration
137       file, as described in pcp.conf(5).
138

SEE ALSO

140       PCPIntro(1), bcc(1), bpf(1) and pmcd(1).
141
142
143
144Performance Co-Pilot                  PCP                           PMDABCC(1)
Impressum