1PMDABCC(1) General Commands Manual PMDABCC(1)
2
6 pmdabcc - BCC PMDA
7
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 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 See the BPF and BCC documentation for detailed description of both.
20
22 pmdabcc reads a mandatory ini-style configuration file:
23 $PCP_PMDAS_DIR/bcc/bcc.conf
25 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 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 prefix (bcc.) *
37 By default, all metrics from the modules will appear un‐
38 der the bcc Performance Metrics Name Space (PMNS) tree,
39 prefix (optional) can be used to change this generic
40 prefix.
41 process_refresh (0)
43 See below.
44 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 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 ap‐
65 peared, 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 For each module listed in modules a corresponding [module] section must
71 be defined containing at least the following options:
72 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 cluster Specifies the unique cluster ID (see PMNS(5)) for the
78 metrics provided by the module under the PMNS path.
79 All modules accept but not necessarily use the boolean debug option.
81 Modules may also support additional module-specific configuration op‐
83 tions, refer to the default configuration file for their supported op‐
84 tions.
85
87 To install, the following must be done as root:
88 # cd $PCP_PMDAS_DIR/bcc
90 # ./Install
91 To uninstall, the following must be done as root:
93 # cd $PCP_PMDAS_DIR/bcc
95 # ./Remove
96 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 in‐
99 stalled or removed.
100 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 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
113 $PCP_PMDAS_DIR/bcc/bcc.conf
114 configuration file for the pmdabcc agent
115 $PCP_PMDAS_DIR/bcc/modules/*.{py,python}
117 PCP BCC PMDA Python modules available for the pmdabcc agent
118 $PCP_PMDAS_DIR/bcc/Install
120 installation script for the pmdabcc agent
121 $PCP_PMDAS_DIR/bcc/Remove
123 undo installation script for the pmdabcc agent
124 $PCP_LOG_DIR/pmcd/bcc.log
126 default log file for messages from the pmdabcc agent
127 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
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
140 PCPIntro(1), bcc(1), bpf(1) and pmcd(1).
141Performance Co-Pilot PCP PMDABCC(1)