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