1PMDA(3) User Contributed Perl Documentation PMDA(3)
2
6 PCP::PMDA - Perl extension for Performance Metrics Domain Agents
7
9 use PCP::PMDA;
10 $pmda = PCP::PMDA->new('myname', $MYDOMAIN);
12 $pmda->connect_pmcd;
14 $pmda->add_metric($pmid, $type, $indom, $sem, $units, 'name', '', '');
16 $pmda->add_indom($indom, [0 => 'white', 1 => 'black', ...], '', '');
17 $pmda->set_fetch(\&fetch_method);
19 $pmda->set_refresh(\&refresh_method);
20 $pmda->set_instance(\&instance_method);
21 $pmda->set_fetch_callback(\&fetch_callback_method);
22 $pmda->set_store_callback(\&store_callback_method);
23 $pmda->set_user('pcp');
25 $pmda->run;
27
29 The PCP::PMDA Perl module contains the language bindings for building
30 Performance Metric Domain Agents (PMDAs) using Perl. Each PMDA exports
31 performance data for one specific domain, for example the operating
32 system kernel, Cisco routers, a database, an application, etc.
33
35 PCP::PMDA->new(name, domain)
36 PCP::PMDA class constructor. name is a string that becomes the
37 name of the PMDA for messages and default prefix for the names of
38 external files used by the PMDA. domain is an integer domain
39 number for the PMDA, usually from the register of domain numbers
40 found in $PCP_VAR_DIR/pmns/stdpmid.
41 $pmda->run()
43 Once all local setup is complete (i.e. instance domains and metrics
44 are registered, callbacks registered - as discussed below) the PMDA
45 must connect to pmcd(1) to complete its initialisation and begin
46 answering client requests for its metrics. This is the role
47 performed by run, and upon invoking it all interaction within the
48 PMDA is done via callback routines (that is to say, under normal
49 cicrumstances, the run routine does not return).
50 The behaviour of the run method is different in the presence of
52 either the PCP_PERL_PMNS or PCP_PERL_DOMAIN environment variables.
53 These can be used to generate the namespace or domain number files,
54 which are used as part of the PMDA installation process.
55 $pmda->connect_pmcd()
57 Allows the PMDA to set up the IPC channel to pmcd(1) and complete
58 the credentials handshake with pmcd(1). If connect_pmcd is not
59 explicitly called the setup and handshake will be done when the run
60 method is called.
61 The advantage of explicitly calling connect_pmcd early in the life
63 of the PMDA is that this reduces the risk of a fatal timeout during
64 the credentials handshake, which may be an issue if the PMDA has
65 considerable work to do, e.g. determining which metrics and
66 instance domains are available, before calling run.
67 $pmda->add_indom(indom, insts, help, longhelp)
69 Define a new instance domain. The instance domain identifier is
70 indom, which is an integer and unique across all instance domains
71 for single PMDA.
72 The instances of the instance domain are defined by insts which can
74 be specified as either a list or a hash.
75 In list form, the contents of the list must provide consecutive
77 pairs of identifier (a integer, unique across all instances in the
78 instance domain) and external instance name (a string, must by
79 unique up to the first space, if any, across all instances in the
80 instance domain). For example:
81 @colours = [0 => 'red', 1 => 'green', 2 => 'blue'];
83 In hash form, the external instance identifier (string) is used as
85 the hash key. An arbitrary value can be stored along with the key
86 (this value is often used as a convenient place to hold the latest
87 value for each metric instance, for example).
88 %timeslices = ('sec' => 42, 'min' => \&min_func, 'hour' => '0');
90 The help and longhelp strings are interpreted as the one-line and
92 expanded help text to be used for this instance domain as further
93 described in pmLookupInDomText(3).
94 Refer also to the replace_indom() discussion below for further
96 details about manipulating instance domains.
97 $pmda->add_metric(pmid, type, indom, sem, units, name, help, longhelp)
99 Define a new metric identified by the PMID pmid and the full metric
100 name name.
101 The metric's metadata is defined by type, indom, sem and units and
103 these parameters are used to set up the pmDesc structure as
104 described in pmLookupDesc(3).
105 The help and longhelp strings are interpreted as the one-line and
107 expanded help text to be used for the metric as further described
108 in pmLookupText(3).
109 $pmda->replace_indom(index, insts)
111 Whenever an instance domain identified by index, previously
112 registered using add_indom(), changes in any way, this change must
113 be reflected by replacing the existing mapping with a new one
114 (insts).
115 The replacement mapping must be a hash if the instance domain was
117 registered initially with add_indom() as a hash, otherwise it must
118 be a list.
119 Refer to the earlier add_indom() discussion concerning these two
121 different types of instance domains definitions.
122 $pmda->load_indom(index)
124 When hash-based instance domains are in use, changes are
125 automatically persisted when using replace_indom() - this persisted
126 indom can be restored (e.g. on startup) using this interface.
127 The instance domain to be loaded is identified by index, previously
129 registered using add_indom().
130 Refer to the earlier add_indom() discussion concerning the two
132 different types of instance domains definitions - only hash-based
133 instance domains are persisted.
134 $pmda->add_pipe(command, callback, data)
136 Allow data to be injected into the PMDA using a pipe(2).
137 The given command is run early in the life of the PMDA, and a pipe
139 is formed between the PMDA and the command. Line-oriented output
140 is assumed (else truncation will occur), and on receipt of each
141 line of text on the pipe, the callback function will be called.
142 The optional data parameter can be used to specify extra data to
144 pass into the callback routine.
145 $pmda->add_sock(hostname, port, callback, data)
147 Create a socket(2) connection to the hostname, port pair. Whenever
148 data arrives (as above, a line-oriented protocol is best) the
149 callback function will be called.
150 The optional data parameter can be used to specify extra data to
152 pass into the callback routine.
153 An opaque integer-sized identifier for the socket will be returned,
155 which can later be used in calls to put_sock() as discussed below.
156 $pmda->put_sock(id, output)
158 Write an output string to the socket identified by id, which must
159 refer to a socket previously registered using add_sock().
160 $pmda->add_tail(filename, callback, data)
162 Monitor the given filename for the arrival of newly appended
163 information. Line-oriented input is assumed (else truncation will
164 occur), and on receipt of each line of text on the pipe, the
165 callback function will be called.
166 The optional data parameter can be used to specify extra data to
168 pass into the callback routine.
169 This interface deals with the issue of the file being renamed (such
171 as on daily log file rotation), and will attempt to automatically
172 re-route information from the new log file if this occurs.
173 $pmda->add_timer(timeout, callback, data)
175 Registers a timer with the PMDA, such that on expiry of a timeout a
176 callback routine will be called. This is a repeating timer.
177 The optional data parameter can be used to specify extra data to
179 pass into the callback routine.
180 $pmda->err(message)
182 Report a timestamped error message into the PMDA log file.
183 $pmda->error(message)
185 Report a timestamped error message into the PMDA log file.
186 $pmda->log(message)
188 Report a timestamped informational message into the PMDA log file.
189 $pmda->set_fetch_callback(cb_function)
191 Register a callback function akin to pmdaSetFetchCallBack(3).
192 $pmda->set_fetch(function)
194 Register a fetch function, as used by pmdaInit(3).
195 $pmda->set_instance(function)
197 Register an instance function, as used by pmdaInit(3).
198 $pmda->set_refresh(function)
200 Register a refresh function, which will be called once per metric
201 cluster, during the fetch operation. Only clusters being requested
202 during this fetch will be refreshed, allowing selective metric
203 value updates within the PMDA.
204 $pmda->set_store_callback(cb_function)
206 Register an store function, used indirectly by pmdaInit(3). The
207 cb_function is called once for each metric/instance pair into which
208 a pmStore(3) is performed.
209 $pmda->set_inet_socket(port)
211 Specify the IPv4 socket port to be used to communicate with
212 pmcd(1).
213 $pmda->set_ipv6_socket(port)
215 Specify the IPv6 socket port to be used to communicate with
216 pmcd(1).
217 $pmda->set_unix_socket(socket_name)
219 Specify the filesystem socket_name path to be used for
220 communication with pmcd(1).
221 $pmda->set_user(username)
223 Run the PMDA under the username user account, instead of the
224 default (root) user.
225
227 pmda_pmid(cluster, item)
228 Construct a Performance Metric Identifier (PMID) from the domain
229 number (passed as an argument to the new constructor), the cluster
230 (an integer in the range 0 to 2^12-1) and the item (an integer in
231 the range 0 to 2^10-1).
232 Every performance metric exported from a PMDA must have a unique
234 PMID.
235 pmda_pmid_name(cluster, item)
237 Perform a reverse metric identifier to name lookup - given the
238 metric cluster and item numbers, returns the metric name string.
239 pmda_pmid_text(cluster, item)
241 Returns the one-line metric help text string - given the metric
242 cluster and item numbers, returns the help text string.
243 pmda_inst_name(index, instance)
245 Perform a reverse instance identifier to instance name lookup for
246 the instance domain identified by index. Given the internal
247 instance identifier, returns the external instance name string.
248 pmda_inst_lookup(index, instance)
250 Given an internal instance identifier (key) for the instance domain
251 identified by index with an associated indom hash, return the value
252 associated with that key. The value can be any scalar value (this
253 includes references, of course, so complex data structures can be
254 referenced).
255 pmda_units(dim_space, dim_time, dim_count, scale_space, scale_time,
257 scale_count)
258 Construct a pmUnits structure suitable for registering a metrics
259 metadata via add_metric().
260 pmda_config(name)
262 Lookup the value for configuration variable name from the
263 /etc/pcp.conf file, using pmGetConfig(3).
264 pmda_uptime(now)
266 Return a human-readable uptime string, based on now seconds since
267 the epoch.
268 pmda_long()
270 Return either PM_TYPE_32 or PM_TYPE_64 depending on the platform
271 size for a signed long integer.
272 pmda_ulong()
274 Return either PM_TYPE_U32 or PM_TYPE_U64 depending on the platform
275 size for an unsigned long integer.
276 pmda_install()
278 Boolean result indicating whether PMDA installation is in progress,
279 or if this is an actual PMDA invocation via pmcd(1).
280
282 Most of the PM_* macros from the PCP C headers are available.
283 For example the type of a metric's value may be directly specified as
285 one of PM_TYPE_32, PM_TYPE_U32, PM_TYPE_64, PM_TYPE_U64, PM_TYPE_FLOAT,
286 PM_TYPE_DOUBLE, PM_TYPE_STRING or PM_TYPE_NOSUPPORT.
287
289 Perl PMDAs do not follow the -D convention of other PCP applications
290 for enabling run-time diagnostics and tracing. Rather the environment
291 variable PCP_PERL_DEBUG needs to be set to a string value matching the
292 syntax accepted for the option value for -D elsewhere, see
293 pmSetDebug(3).
294 This requires a little trickery. The pmcd(1) configuration file
296 (PCP_PMCDCONF_PATH from /etc/pcp.conf) needs hand editing. This is
297 best demonstrated by example.
298 Replace this line
300 foo 242 pipe binary python /somepath/foo.py
302 with
304 foo 242 pipe binary python \
306 sh -c "PCP_PERL_DEBUG=pdu,fetch /usr/bin/python /somepath/foo.py"
307
309 perl(1) and PCPIntro(1).
310 The PCP mailing list pcp@groups.io can be used for questions about this
312 module.
313 Further details can be found at https://pcp.io
315
317 The Performance Co-Pilot development team.
318 Copyright (C) 2014 Red Hat. Copyright (C) 2008-2010 Aconex. Copyright
320 (C) 2004 Silicon Graphics, Inc.
321 This library is free software; you can redistribute it and/or modify it
323 under the terms of the GNU General Public License, version 2 (see the
324 "COPYING" file in the PCP source tree for further details).
325perl v5.28.1 2019-03-13 PMDA(3)