1PMDA(3) Library Functions Manual PMDA(3)
2
6 PMDA - introduction to the Performance Metrics Domain Agent support
7 library
8
10 #include <pcp/pmapi.h>
11 #include <pcp/pmda.h>
12 ... assorted routines ...
14 cc ... -lpcp_pmda -lpcp
16
18 To assist in the development of Performance Metric Domain Agents
19 (PMDAs) for the Performance Co-Pilot (PCP), a procedural interface is
20 provided that extends the Performance Metrics Application Programming
21 Interface (PMAPI(3)) library. These procedures are designed to enable
22 a programmer to quickly build a PMDA which can then be tested and
23 refined. However, this also implies that a PMDA has a particular
24 structure which may not be suitable for all PMDA implementations.
25 Once you are familiar with the PCP and PMDA frameworks, you can quickly
27 implement a new PMDA with only a few data structures and functions.
28 This is covered in far greater detail in the Performance Co-Pilot Pro‐
29 grammer's Guide.
30 A PMDA is responsible for a set of performance metrics, in the sense
32 that it must respond to requests from pmcd(1) for information about
33 performance metrics, instance domains, and instantiated values.
34 This man page contains sections of the simple PMDA which is located at
36 $PCP_PMDAS_DIR/simple.
37
39 Two approaches may be used for connecting a PMDA to a pmcd(1) process.
40 A Dynamic Shared Object (DSO) can be attached by pmcd(1) using
41 dlopen(3) when the pmcd(1) process is started. A procedural interface
42 referenced through a shared data structure is used to handle requests
43 from pmcd(1) to the PMDA .
44 The preferred approach is for a separate process (daemon) to communi‐
46 cate with pmcd(1) using the Performance Data Units (PDU) Inter-Process
47 Communication (IPC) protocol.
48 All PMDAs are launched and controlled by the pmcd(1) process on the
50 local host. The requests from the clients are received by pmcd(1) and
51 forwarded to the appropriate PMDAs. Responses, when required, are
52 returned through pmcd(1) to the clients. The requests (PDUs) that may
53 be sent to a PMDA from pmcd(1) are PDU_FETCH, PDU_PROFILE,
54 PDU_INSTANCE_REQ, PDU_DESC_REQ, PDU_TEXT_REQ and PDU_RESULT. If the
55 PMDA implements any dynamic metrics it may also receive PDU_PMNS_CHILD,
56 PDU_PMNS_IDS, PDU_PMNS_NAMES and PDU_PMNS_TRAVERSE PDUs.
57
59 To allow a consistent framework, pmdaMain(3) can be used by a daemon
60 PMDA to handle the communication protocol using the same callbacks as a
61 DSO PMDA. The structure pmdaInterface is used to convey the common
62 procedural interface and state information that is used by pmcd(1) and
63 a PMDA. This state information includes tables describing the sup‐
64 ported metrics and instance domains.
65 As most of the procedural interface is identical for all PMDAs, they
67 are provided as part of this support library (pmdaProfile(3),
68 pmdaFetch(3), pmdaInstance(3), pmdaDesc(3), pmdaText(3) and pmdaS‐
69 tore(3)). However, these routines require access to the pmdaInterface
70 state information so it must be correctly initialized using pmdaCon‐
71 nect(3), pmdaDaemon(3), pmdaOpenLog(3), pmdaDSO(3), pmdaGetOpt(3) and
72 pmdaInit(3).
73
75 Three structures are declared in /usr/include/pcp/pmda.h which provide
76 a framework for declaring the metrics and instances supported by the
77 PMDA.
78 Every instance requires a unique integer identifier and a unique name,
80 as defined by the structure pmdaInstid:
81 /*
83 * Instance description: index and name
84 */
85 typedef struct {
87 int i_inst; /* internal instance identifier */
88 char *i_name; /* external instance identifier */
89 } pmdaInstid;
90 An instance domain requires its own unique identification (pmInDom),
92 the number of instances the domain represents, and a pointer to an
93 array of instance descriptions. This is defined in the structure
94 pmdaIndom:
95 /*
97 * Instance domain description: unique instance id,
98 * number of instances in this domain, and the list of
99 * instances (not null terminated).
100 */
101 typedef struct {
103 pmInDom it_indom; /* indom, filled in */
104 int it_numinst; /* number of instances */
105 pmdaInstid *it_set; /* instance identifiers */
106 } pmdaIndom;
107 The simple PMDA has one instance domain for simple.color with three
109 instances (red, green and blue), and a second instance domain for sim‐
110 ple.now with instances which can be specified at run-time. These
111 instance domains are defined as:
112 static pmdaInstid _color[] = {
114 { 0, "red" }, { 1, "green" }, { 2, "blue" }
115 };
116 static pmdaInstid *_timenow = NULL;
117 static pmdaIndom indomtab[] = {
119 #define COLOR_INDOM 0
120 { COLOR_INDOM, 3, _color },
121 #define NOW_INDOM 1
122 { NOW_INDOM, 0, NULL },
123 };
124 The preprocessor macros COLOR_INDOM and NOW_INDOM are used in the met‐
126 ric description table to identify the instance domains of individual
127 metrics. These correspond to the serial value in the instance domain
128 pmInDom structure (the domain field is set by pmdaInit(3) at run-time).
129 The serial value must be unique for each instance domain within the
130 PMDA.
131 The indom table shown above which is usually passed to pmdaInit(3) does
133 not need to be created if one wants to write one's own Fetch and
134 Instance functions. See pmdaInit(3) for more details.
135
137 Every PMDA has its own unique namespace using the format defined in
138 PMNS(5). In summary, the namespace matches the names of the metrics to
139 the unique identifier. The simple PMDA defines five metrics: sim‐
140 ple.numfetch, simple.color, simple.time.user, simple.time.sys and sim‐
141 ple.now. The namespace for these metrics is defined in
142 $PCP_PMDAS_DIR/simple/pmns and is installed as:
143 simple {
145 numfetch 253:0:0
146 color 253:0:1
147 time
148 now 253:2:4
149 }
150 simple.time {
152 user 253:1:2
153 sys 253:1:3
154 }
155 The domain number of 253 is obtained from $PCP_VAR_DIR/pmns/stdpmid.
157 New PMDAs should specify a unique domain number in this file, and
158 obtain the number during installation. This allows the domain number
159 to change by modifying only the file $PCP_VAR_DIR/pmns/stdpmid.
160 The simple.time and simple.now metrics are defined in separate clusters
162 to the other metrics which allows a PMDA to support more than 1024 met‐
163 rics, as well as grouping similar metrics together. Therefore, the
164 item numbers for a new cluster may be identical to the item numbers in
165 other clusters. The simple PMDA continues to increment the item num‐
166 bers to permit direct mapping (see pmdaInit(3)).
167 The namespace file should be installed and removed with the agent using
169 pmnsadd(1) and pmnsdel(1). See the later sections on INSTALLATION and
170 REMOVAL.
171 A simple ASCII namespace can be constructed by creating a file similar
173 to $PCP_PMDAS_DIR/simple/root:
174 /*
176 * fake "root" for validating the local PMNS subtree
177 */
178 #include "$PCP_VAR_DIR/pmns/stdpmid"
180 root { simple }
182 #include "pmns"
184 and can be referred to with the -n option in most PCP tools.
187
189 Each metric requires a description (pmDesc), which contains its Perfor‐
190 mance Metric Identifier (PMID), data type specification, instance
191 domain, semantics and units (see pmLookupDesc(3)). A handle is also
192 provided for application specific information in the pmdaMetric struc‐
193 ture:
194 /*
196 * Metric description: handle for extending description,
197 * and the description.
198 */
199 typedef struct {
201 void* m_user; /* for users external use */
202 pmDesc m_desc; /* metric description */
203 } pmdaMetric;
204 The simple PMDA defines the metrics as:
206 static pmdaMetric metrictab[] = {
208 /* numfetch */
209 { (void *)0,
210 { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
211 { 0,0,0,0,0,0} }, },
212 /* color */
213 { (void *)0,
214 { PMDA_PMID(0,1), PM_TYPE_32, COLOR_INDOM, PM_SEM_INSTANT,
215 { 0,0,0,0,0,0} }, },
216 /* time.user */
217 { (void*)0,
218 { PMDA_PMID(1,2), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER,
219 { 0, 1, 0, 0, PM_TIME_SEC, 0 } }, },
220 /* time.sys */
221 { (void*)0,
222 { PMDA_PMID(1,3), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER,
223 { 0, 1, 0, 0, PM_TIME_SEC, 0 } }, },
224 /* now */
225 { NULL,
226 { PMDA_PMID(2,4), PM_TYPE_U32, NOW_INDOM, PM_SEM_INSTANT,
227 { 0,0,0,0,0,0 } }, },
228 };
229 The macro PMDA_PMID (defined in /usr/include/pcp/pmda.h) is used to
231 specify each metric's cluster and item fields of the associated pmID.
232 As with instance domains, the domain field is set by pmdaInit(3) at
233 run-time, however, the default domain is assumed to be defined by the
234 PMDA in the macro MYDOMAIN.
235 The metric table shown above which is usually passed to pmdaInit(3)
237 does not need to be created if one wants to write one's own Fetch and
238 Descriptor functions. See pmdaInit(3) for more details.
239
241 A PMDA that is run as a DSO is opened by pmcd(1) with dlopen(3).
242 pmcd(1) will call the PMDA's initialization function that is specified
243 in $PCP_PMCDCONF_PATH. This function is passed a pointer to a pmdaIn‐
244 terface structure which must be completed. Any callbacks which are not
245 the default PMDA support library callbacks must be specified in the
246 pmdaInterface structure.
247 The simple PMDA uses its own store and fetch callback. simple_fetch()
249 calls pmdaFetch(3) which requires a callback to be set with pmdaSet‐
250 FetchCallBack(3) as can be seen in $PCP_PMDAS_DIR/simple/simple.c.
251 The flag _isDSO is used to determine if the PMDA is a daemon or a DSO
253 so that the correct initialization routine, pmdaDaemon(3) or
254 pmdaDSO(3), is called.
255
257 A PMDA that is run as a daemon is forked and executed by pmcd(1).
258 Therefore, unlike a DSO PMDA, the starting point for a daemon PMDA is
259 main(). The agent should parse the command line arguments, create a
260 log file and initialize some data structures that pmcd(1) would ini‐
261 tialize for a DSO agent.
262 The pmdaInterface structure must be completely defined by the daemon
264 PMDA. The function pmdaDaemon(3) can be called at the start of main()
265 to set most of these fields. Command line parsing can be simplified by
266 using pmdaGetOpt(3), which is similar to getopt(2), but extracts a com‐
267 mon set of options into the pmdaInterface structure. stderr can be
268 mapped to a log file using pmdaOpenLog(3) to simplify debugging and
269 error messages. The connection to pmcd(1) can be made with pmdaCon‐
270 nect(3) and the loop which handles the incoming PDUs, pmdaMain(3),
271 should be the last function called. This can be seen in
272 $PCP_PMDAS_DIR/simple/simple.c.
273 The simple_init() routine is common to an agent that can be run as both
275 a Daemon and DSO PMDA.
276
278 Each PMDA must be able to provide pmcd(1) with the help text for each
279 metric. Most PMDAs use specially created files with indexes to support
280 efficient retrieval of the help text. Tools are provided with PCP to
281 create the help text files of appropriate format. See newhelp(1).
282
284 A series of shell procedures are defined in
285 $PCP_SHARE_DIR/lib/pmdaproc.sh which greatly simplify the installation
286 and removal of a PMDA.
287 The Install scripts for most PMDAs should only need to specify the name
289 of the PMDA in iam, call pmdaSetup which sets up some default vari‐
290 ables, checks permissions (you have to be ``root'' to install or remove
291 a PMDA), checks that you're in the right directory (somewhere that ends
292 with /pmdas/$iam), optionally generate the Performance Metrics Name
293 Space (PMNS) and PMDA domain number files for Perl or Python PMDAs,
294 checks the PMDA domain number is valid, etc., specify the communication
295 protocols, and finally call pmdaInstall to do all the work of updating
296 the PMNS, updating the pmcd(1) control file, notifying or restarting
297 pmcd(1),
298 Beyond pmdaSetup and pmdaInstall, another optional helper routines is
300 pmdaChooseConfigFile that may be used to interactively select or create
301 a PMDA-specific configuration file, e.g. pmdalogger(1).
302 The Remove scripts are even simpler as setting up the communication
304 protocols are not required, so set the name of the PMDA in iam, then
305 call pmdaSetup followed by a call to pmdaRemove.
306 Further information is contained in the $PCP_SHARE_DIR/lib/pmdaproc.sh
308 file and the following section.
309 Optionally, a PMDA may provide an Upgrade script alongside Install and
311 Remove. If present this script will be used by the pmcd startup
312 process to ensure corrections to an installation have been made before
313 starting the PMDA. Examples of such corrections include: updates to
314 pmcd.conf when a PMDA script or binary has been renamed, when the PMDA
315 supports a new format of its configuration file, or if there is some
316 latent problem from an earlier install (e.g. some PMDAs may need to
317 introduce use of the notready keyword in pmcd.conf, as described
318 below).
319
321 As outlined below there are a number of variables that can be set in a
322 PMDA's Install script to influence the behaviour of the installation
323 procedures. These would typically need to be set before the call to
324 pmdaInstall, but in some instances (like $iam and the cases specifi‐
325 cally noted below), before the call to pmdaSetup.
326 The following variables control the communication options between the
328 PMDA and pmcd(1). At least one of $daemon_opt, $dso_opt, $perl_opt or
329 $python_opt must be set to define the supported mode(s) of communica‐
330 tion. If more than one of these is set the user will be prompted to
331 make a selection when the Install script is run.
332 daemon_opt We are willing to install the PMDA as a daemon.
334 Default: true
335 dso_opt We are willing to install the PMDA as a DSO, so pmcd(1)
337 will use the dynamic linking loader to attach the
338 PMDA's DSO at run-time and communication from pmcd(1)
339 to the PMDA and back uses procedure calls, not an IPC
340 channel.
341 Default: false
342 dso_entry For a DSO PMDA, this is the name of the PMDA's initial‐
344 ization routine.
345 Default: ${iam}_init
346 dso_name For a DSO PMDA, this is the full pathanme of the PMDA's
348 DSO file.
349 Default: $PCP_PMDAS_DIR/$iam/pmda_$iam.$dso_suffix
350 pipe_opt For a daemon PMDA, is the default IPC channel via a
352 pipe(2)?
353 Default: Platform-specific, so true for most, but false
354 for Windows
355 perl_opt We are willing to install the PMDA as a Perl script and
357 pmcd(1) will use the perl(1) interpreter to run the
358 PMDA.
359 Default: false
360 pmda_dir Full pathname to the directory where the PMDA's instal‐
362 lation files (executable, script, PMNS source, help
363 text source, etc) are to be found.
364 Default: output from pwd(1)
365 If set, must be done before the call to pmdaSetup.
367 pmda_name For a daemon PMDA, this is the name of the PMDA's exe‐
369 cutable binary relative to the $pmda_dir directory.
370 Default: pmda$iam
371 python_opt We are willing to install the PMDA as a Python script
373 and pmcd(1) will use the python(1) interpreter to run
374 the PMDA.
375 Default: false
376 ipc_prot For a daemon PMDA, this can be set to either binary or
378 text. The default is binary and text is rarely used.
379 In addition, an optional IPC parameter notready can be
380 used to signify that the PMDA will start up in the
381 notready state, e.g. ipc_prot="binary notready". Note
382 that the quotes are required. The IPC parameters for a
383 PMDA appear in pmcd.conf in the IPC Params column. For
384 further details, see pmcd(1) but basically pmcd will
385 not issue any requests to a PMDA that has started in
386 the notready state until the PMDA sends a
387 PM_ERR_PMDAREADY PDU. This allows PMDAs with long
388 startup times to initialize correctly without timing
389 out. For details, see pmdaSendError(3) and pmcd(1).
390 When a PMDA is in the notready state, any client
391 requests sent to pmcd for the PMDA domain will return
392 with the PM_ERR_PMDANOTREADY error.
393 socket_inet_def For a daemon PMDA using a socket(2) as the IPC channel
395 the default Internet port number or service name (if
396 known).
397 Default: ""
398 socket_opt For a daemon PMDA, is the default IPC channel via a
400 socket(2)?
401 Default: Platform-specific, so false for most, but true
402 for Windows
403 The following variables control the PMNS options.
405 pmns_dupok Most PMDAs do not have duplicate names for the same
407 PMID in their PMNS. But if this is not the case,
408 pmns_dupok should be set to true.
409 Default: false
410 pmns_name Each PMDA will add one or more non-leaf nodes to the
412 top of the PMNS. The most common case is that all of
413 the metrics for a PMDA will be placed below the node
414 named $iam. If this is not the case, and especially
415 when the PMDA adds more than one non-leaf node at the
416 top of the PMNS, pmns_name needs to be set to the list
417 of node names (separated by white space), e.g. for
418 pmdaproc(1) pmns_name is set to "proc cgroup hotproc".
419 Default: $iam
420 It is most important that if pmns_name is set to a non-
422 default value in the Install script then it must also
423 be set to the same value in the Remove script.
424 pmns_source The name of the PMDA's PMNS source file. By default,
426 the name is interpreted as a relative pathname from the
427 $pmda_dir directory.
428 Default: pmns
429 The following variables provide assorted additional options associated
431 with the installation of a PMDA.
432 args Additional command line args for the PMDA. These will
434 be appended to the PMDA's control line in $PCP_PMCD‐
435 CONF_PATH.
436 Default: ""
437 check_delay Delay (in seconds) after finishing the PMDA installa‐
439 tion (or removal) before checking the availability of
440 metrics from the PMDA. May need to be increased if the
441 PMDA has a lengthy startup procedure.
442 Default: 0.3
443 signal_delay Delay (in seconds) after notifying pmcd(1) with a sig‐
445 nal. Required to allow pmcd(1) to complete processing
446 before proceeding to the next step of the installation
447 (or removal).
448 Default: 1
449 configdir Determines the directory in which a PMDA's configura‐
451 tion file will be stored. Used by pmdaChooseConfigFile
452 so should be set before calling that procedure.
453 Default: $PCP_VAR_DIR/config/$iam
454 configfile Preferred configuration file for the PMDA. Used by
456 pmdaChooseConfigFile so should be set before calling
457 that procedure.
458 Default: ""
459 default_configfile
461 Default configuration file for the PMDA. Used by pmda‐
462 ChooseConfigFile so should be set before calling that
463 procedure.
464 Default: ""
465 dso_suffix Standard suffix for a DSO. Should not need to be
467 changed under normal circumstances.
468 Default: Platform-specific, so 'so' for Linux, 'dylib'
469 for Mac OS X, 'dll' for Windows, etc.
470 If set, must be done before the call to pmdaSetup.
472 help_source The name of the help text source file that should be
474 used as input to pmnewhelp(1). By default, the name is
475 interpreted as a relative pathname from the $pmda_dir
476 directory.
477 Default: help
478 python_name Full pathname of the Python script for a Python PMDA.
480 Default: $pmda_dir/pmda$iam.python or
481 $pmda_dir/pmda$iam.py
482 The shell procedures in $PCP_SHARE_DIR/lib/pmdaproc.sh manipulate a
484 number of temporary files using the variable $tmp as the prefix for the
485 name of the temporary files. $tmp is a directory that is created, used
486 and removed internally within the procedures of
487 $PCP_SHARE_DIR/lib/pmdaproc.sh but can also be used as the prefix for
488 temporary files needed by a PMDA's Install or Remove scripts. When
489 used in this way, $tmp should be followed by a ``/'' and then a suffix,
490 e.g. $tmp/myfoo. The Install and Remove scripts should not use other
491 temporary file name prefixes nor use sh(1) trap statements to clean up
492 temporary files as this is all done within
493 $PCP_SHARE_DIR/lib/pmdaproc.sh.
494
496 Any PMDA which uses this library can set PMAPI(3) debugging control
497 option libpmda (with -Dlibpmda on the command line or via 3pmSetDe‐
498 bug[1m(3)) to to enable the display of debugging information which may be
499 useful during development (see pmdbg(1)).
500 The status field of the pmdaInterface structure should be zero after
502 pmdaDaemon, pmdaDSO, pmdaGetOpt, pmdaConnect and pmdaInit are called.
503 A value less than zero indicates that initialization has failed.
504 Some error messages that are common to most functions in this library
506 are:
507 PMDA interface version interface not supported
509 Most of the functions require that the comm.version
510 field of the pmdaInterface structure be set to
511 PMDA_INTERFACE_2 or later. PMDA_INTERFACE_2 or
512 PMDA_INTERFACE_3 implies that the version.two fields are
513 correctly initialized, while PMDA_INTERFACE_4 implies
514 that the version.four fields are correctly initialized
515 (see pmdaDaemon(3) and pmdaDSO(3)).
516
518 Failing to complete any of the data structures or calling any of the
519 library routines out of order may cause unexpected behavior in the
520 PMDA.
521 Due to changes to the PMAPI(3) and PMDA(3) API in the PCP 2.0 release,
523 as described in the product release notes, PMDAs built using PCP 2.0
524 must specify PMDA_INTERFACE_2 or later and link with libpcp_pmda.so.2
525 and libpcp.so.2. Pre-existing Daemon PMDAs specifying PMDA_PROTOCOL_1
526 will continue to function using the backwards compatible
527 libpcp_pmda.so.1 and libpcp.so.1 libraries and may be recompiled using
528 the headers installed in /usr/include/pcp1.x/ without any modification.
529 These backwards compatible headers and libraries are contained in the
530 pcp.sw.compat subsystem.
531
533 /usr/include/pcp/pmda.h
534 Header file for the PMDA support library.
535 /usr/lib/libpcp_pmda.so
537 Dynamic library containing PMDA support library routines.
538 $PCP_PMDAS_DIR/trivial
540 The source of the trivial PMDA.
541 $PCP_PMDAS_DIR/simple
543 The source of the simple PMDA.
544 $PCP_PMDAS_DIR/txmon
546 The source of the txmon PMDA.
547 $PCP_PMCDCONF_PATH
549 Configuration file for pmcd(1).
550 $PCP_VAR_DIR/pmns
552 Location of namespace descriptions for every PMDA.
553 $PCP_VAR_DIR/pmns/stdpmid
555 The unique domain identifiers for each PMDA.
556 $PCP_SHARE_DIR/lib/pmdaproc.sh
558 Shell procedures for installing and removing a PMDA.
559
561 Environment variables with the prefix PCP_ are used to parameterize the
562 file and directory names used by PCP. On each installation, the file
563 /etc/pcp.conf contains the local values for these variables. The
564 $PCP_CONF variable may be used to specify an alternative configuration
565 file, as described in pcp.conf(5). Values for these variables may be
566 obtained programmatically using the pmGetConfig(3) function.
567
569 dbpmda(1), newhelp(1), pmcd(1), pmnsadd(1), pmnsdel(1), PMAPI(3), PMWE‐
570 BAPI(3), pmdaConnect(3), pmdaDaemon(3), pmdaDesc(3), pmdaDSO(3),
571 pmdaFetch(3), pmdaGetOpt(3), pmdaInit(3), pmdaInstance(3), pmdaMain(3),
572 pmdaOpenLog(3), pmdaProfile(3), pmdaStore(3), pmdaText(3),
573 pmLookupDesc(3) and PMNS(5).
574 For a complete description of the pcp_pmda library and the PMDA devel‐
576 opment process, refer to the Insight book Performance Co-Pilot Program‐
577 mer's Guide.
578Performance Co-Pilot PCP PMDA(3)