1PMDA(3)               User Contributed Perl Documentation              PMDA(3)
2
3
4

NAME

6       PCP::PMDA - Perl extension for Performance Metrics Domain Agents
7

SYNOPSIS

9         use PCP::PMDA;
10
11         $pmda = PCP::PMDA->new('myname', $MYDOMAIN);
12
13         $pmda->connect_pmcd;
14
15         $pmda->add_metric($pmid, $type, $indom, $sem, $units, 'name', '', '');
16         $pmda->add_indom($indom, [0 => 'white', 1 => 'black', ...], '', '');
17
18         $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
24         $pmda->set_user('pcp');
25
26         $pmda->run;
27

DESCRIPTION

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

METHODS

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
42       $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
51           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
56       $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
62           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
68       $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
73           The instances of the instance domain are defined by insts which can
74           be specified as either a list or a hash.
75
76           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
82            @colours = [0 => 'red', 1 => 'green', 2 => 'blue'];
83
84           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
89            %timeslices = ('sec' => 42, 'min' => \&min_func, 'hour' => '0');
90
91           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
95           Refer also to the replace_indom() discussion below for further
96           details about manipulating instance domains.
97
98       $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
102           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
106           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
110       $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
116           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
120           Refer to the earlier add_indom() discussion concerning these two
121           different types of instance domains definitions.
122
123       $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
128           The instance domain to be loaded is identified by index, previously
129           registered using add_indom().
130
131           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
135       $pmda->add_pipe(command, callback, data)
136           Allow data to be injected into the PMDA using a pipe(2).
137
138           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
143           The optional data parameter can be used to specify extra data to
144           pass into the callback routine.
145
146       $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
151           The optional data parameter can be used to specify extra data to
152           pass into the callback routine.
153
154           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
157       $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
161       $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
167           The optional data parameter can be used to specify extra data to
168           pass into the callback routine.
169
170           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
174       $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
178           The optional data parameter can be used to specify extra data to
179           pass into the callback routine.
180
181       $pmda->err(message)
182           Report a timestamped error message into the PMDA log file.
183
184       $pmda->error(message)
185           Report a timestamped error message into the PMDA log file.
186
187       $pmda->log(message)
188           Report a timestamped informational message into the PMDA log file.
189
190       $pmda->set_fetch_callback(cb_function)
191           Register a callback function akin to pmdaSetFetchCallBack(3).
192
193       $pmda->set_fetch(function)
194           Register a fetch function, as used by pmdaInit(3).
195
196       $pmda->set_instance(function)
197           Register an instance function, as used by pmdaInit(3).
198
199       $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
205       $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
210       $pmda->set_inet_socket(port)
211           Specify the IPv4 socket port to be used to communicate with
212           pmcd(1).
213
214       $pmda->set_ipv6_socket(port)
215           Specify the IPv6 socket port to be used to communicate with
216           pmcd(1).
217
218       $pmda->set_unix_socket(socket_name)
219           Specify the filesystem socket_name path to be used for
220           communication with pmcd(1).
221
222       $pmda->set_user(username)
223           Run the PMDA under the username user account, instead of the
224           default (root) user.
225

HELPER METHODS

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
233           Every performance metric exported from a PMDA must have a unique
234           PMID.
235
236       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
240       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
244       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
249       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
256       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
261       pmda_config(name)
262           Lookup the value for configuration variable name from the
263           /etc/pcp.conf file, using pmGetConfig(3).
264
265       pmda_uptime(now)
266           Return a human-readable uptime string, based on now seconds since
267           the epoch.
268
269       pmda_long()
270           Return either PM_TYPE_32 or PM_TYPE_64 depending on the platform
271           size for a signed long integer.
272
273       pmda_ulong()
274           Return either PM_TYPE_U32 or PM_TYPE_U64 depending on the platform
275           size for an unsigned long integer.
276
277       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

MACROS

282       Most of the PM_* macros from the PCP C headers are available.
283
284       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

DEBUGGING

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
295       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
299       Replace this line
300
301        foo  242  pipe  binary  python  /somepath/foo.py
302
303       with
304
305        foo  242  pipe  binary  python  \
306            sh -c "PCP_PERL_DEBUG=pdu,fetch /usr/bin/python /somepath/foo.py"
307

SEE ALSO

309       perl(1) and PCPIntro(1).
310
311       The PCP mailing list pcp@groups.io can be used for questions about this
312       module.
313
314       Further details can be found at https://pcp.io
315

AUTHOR

317       The Performance Co-Pilot development team.
318
319       Copyright (C) 2014 Red Hat.  Copyright (C) 2008-2010 Aconex.  Copyright
320       (C) 2004 Silicon Graphics, Inc.
321
322       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).
325
326
327
328perl v5.36.0                      2022-11-11                           PMDA(3)
Impressum