1PMDABCC(1) General Commands Manual PMDABCC(1)
2
6 pmdabcc - BCC PMDA
7
9 pmdabcc is a Performance Metrics Domain Agent (PMDA) which extracts
10 live performance data from extended BPF (Berkeley Packet Filter) in-
11 kernel programs by using BCC (BPF Compiler Collection) Python frontend.
12 pmdabcc loads and acts as a bridge for any number of configured, sepa‐
14 rate PCP BCC PMDA Python modules running BPF programs. Existing BCC
15 Python tools and programs should be possible to be utilized with PCP
16 BCC PMDA modules with reasonable effort.
17 See the BPF and BCC documentation for detailed description of both.
19
21 pmdabcc reads a mandatory ini-style configuration file
22 · $PCP_PMDAS_DIR/bcc/bcc.conf
24 This file contains in its [pmda] section values for the following PMDA
26 options:
27 · modules
29 · prefix
30 · process_refresh
31 · module_failure_fatal
32 pmdabcc reads module-specific configuration for each module listed in
34 the comma-separated list of modules (mandatory). By default, all met‐
35 rics from the modules will appear under the bcc Performance Metrics
36 Name Space (PMNS) tree, prefix (optional) can be used to change this
37 generic prefix. A boolean value for module_failure_fatal (optional)
38 controls whether a module failing to compile should cause the whole
39 PMDA to abort (this is the default) or to start up with any possibly
40 functional modules. Module configuration errors and internal errors
41 (such as failing to register the provided PMNS metrics) will always
42 cause the PMDA to fail.
43 Of particular note, the process option accepted by some modules eval‐
45 utes the given PIDs and process names at PMDA/module initialization
46 time and apply filtering for only those processes found at that stage.
47 This is due to fact that the in-kernel BPF program is compiled at mod‐
48 ule initialization time and, even more importantly, they are often run‐
49 ning at performance critical areas where it is not acceptable to do
50 process name lookups each time a request is processed by the BPF pro‐
51 gram. To allow modules to monitor named processes (say, process =
52 java) even if they restart the process_refresh should be set to a non-
53 negative integer N to dynamically refresh monitored processes every N
54 seconds. In case new processes matching the process filter have
55 appeared, the currently running BPF is detached and a new BPF program
56 with updated PID information is installed (and if no PIDs matching the
57 filter are anymore present, the BPF program will be detach to avoid any
58 needless overhead).
59 For each listed module a corresponding [module] section must be defined
61 containing at least the following options:
62 · module
64 · cluster
65 module defines the actual Python module file name to be loaded during
67 PMDA startup under the modules subdirectory of the PCP BCC PMDA instal‐
68 lation. cluster specifies the cluster ID (see PMNS(5)) for the metrics
69 provided by the module under the PMNS path. Optionally, prefix can be
70 defined to override the generic value described above. All modules
71 accept but not necessarily use the boolean debug option.
72 Modules may also support additional module-specific configuration
74 options, refer to the default configuration file for their supported
75 options.
76 Once the needed setup is ready, you can install the PMDA to load the
78 configured modules and the BPF programs they utilize. To install, do
79 the following as root:
80 # cd $PCP_PMDAS_DIR/bcc
82 # ./Install
83 To uninstall, do the following as root:
85 # cd $PCP_PMDAS_DIR/bcc
87 # ./Remove
88 pmdabcc is launched by pmcd(1) and should never be executed directly.
90 The Install and Remove scripts notify pmcd(1) when the agent is
91 installed or removed.
92 In case module_failure_fatal is set to false, the PMDA installation
94 will be considered successful even if some or even all configured mod‐
95 ules fail to load, in such cases metric values provided by the failing
96 modules will not be available. The pmdabcc agent log file (see below)
97 will contain detailed information about activation of each module.
98 Some modules will start providing values only after having collected
100 data from related system activity. For instance, the tcpperpid module
101 will not provide any values unless there are processes generating TCP
102 traffic on the system.
103
105 $PCP_PMDAS_DIR/bcc/bcc.conf
106 configuration file for the pmdabcc agent
107 $PCP_PMDAS_DIR/bcc/modules/*.{py,python}
109 PCP BCC PMDA Python modules available for the pmdabcc agent
110 $PCP_PMDAS_DIR/bcc/Install
112 installation script for the pmdabcc agent
113 $PCP_PMDAS_DIR/bcc/Remove
115 undo installation script for the pmdabcc agent
116 $PCP_LOG_DIR/pmcd/bcc.log
118 default log file for messages from the pmdabcc agent
119
121 Environment variables with the prefix PCP_ are used to parameterize the
122 file and directory names used by PCP. On each installation, the file
123 /etc/pcp.conf contains the local values for these variables. The
124 $PCP_CONF variable may be used to specify an alternative configuration
125 file, as described in pcp.conf(5).
126
128 PCPIntro(1), bcc(1), bpf(1), and pmcd(1).
129Performance Co-Pilot PCP PMDABCC(1)