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 · module_failure_fatal
31 pmdabcc reads module-specific configuration for each module listed in
33 the comma-separated list of modules (mandatory). By default, all met‐
34 rics from the modules will appear under the bcc Performance Metrics
35 Name Space (PMNS) tree, prefix (optional) can be used to change this
36 generic prefix. A boolean value for module_failure_fatal (optional)
37 controls whether a module failing to compile should cause the whole
38 PMDA to abort (this is the default) or to start up with any possibly
39 functional modules. Module configuration errors and internal errors
40 (such as failing to register the provided PMNS metrics) will always
41 cause the PMDA to fail.
42 For each listed module a corresponding [module] section must be defined
44 containing at least the following options:
45 · module
47 · cluster
48 module defines the actual Python module file name to be loaded during
50 PMDA startup under the modules subdirectory of the PCP BCC PMDA instal‐
51 lation. cluster specifies the cluster ID (see PMNS(5)) for the metrics
52 provided by the module under the PMNS path. Optionally, prefix can be
53 defined to override the generic value described above. All modules
54 accept but not necessarily use the boolean debug option.
55 Modules may also support additional module-specific configuration
57 options, refer to the default configuration file and each Python module
58 for their supported options. Of particular note, the process option
59 accepted by some modules evalutes the given PIDs and process names at
60 PMDA/module initialization time and apply filtering for only those pro‐
61 cesses found at that stage. In other words, it is not possible to
62 define, say, process = java and expect all future Java processes to be
63 traced by such modules. (This is due to fact that the in-kernel BPF
64 program is constructed at module initialization time and, even more
65 importantly, they are often running at performance critical areas where
66 it is not acceptable to do process name lookups each time a request is
67 processed by a BPF program.)
68 Once the needed setup is ready, you can install the PMDA to load the
70 configured modules and the BPF programs they utilize. To install, do
71 the following as root:
72 # cd $PCP_PMDAS_DIR/bcc
74 # ./Install
75 To uninstall, do the following as root:
77 # cd $PCP_PMDAS_DIR/bcc
79 # ./Remove
80 pmdabcc is launched by pmcd(1) and should never be executed directly.
82 The Install and Remove scripts notify pmcd(1) when the agent is
83 installed or removed.
84 Note that the PMDA installation will be considered successful even if
86 some or even all configured modules fail to load, in such cases metrics
87 provided by the failing modules will not be available. The pmdabcc
88 agent log file (see below) will contain detailed information about
89 activation of each module.
90 Some modules will start providing values only after having collected
92 data from related system activity. For instance, the tcplife module
93 will not provide any values unless there are processes generating TCP
94 traffic running on the system.
95
97 $PCP_PMDAS_DIR/bcc/bcc.conf
98 configuration file for the pmdabcc agent
99 $PCP_PMDAS_DIR/bcc/modules/*.{py,python}
101 PCP BCC PMDA Python modules available for the pmdabcc agent
102 $PCP_PMDAS_DIR/bcc/Install
104 installation script for the pmdabcc agent
105 $PCP_PMDAS_DIR/bcc/Remove
107 undo installation script for the pmdabcc agent
108 $PCP_LOG_DIR/pmcd/bcc.log
110 default log file for messages from the pmdabcc agent
111
113 Environment variables with the prefix PCP_ are used to parameterize the
114 file and directory names used by PCP. On each installation, the file
115 /etc/pcp.conf contains the local values for these variables. The
116 $PCP_CONF variable may be used to specify an alternative configuration
117 file, as described in pcp.conf(5).
118
120 PCPIntro(1), bcc(1), bpf(1), and pmcd(1).
121Performance Co-Pilot PCP PMDABCC(1)