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