1PMLOADDERIVEDCONFIG(3)     Library Functions Manual     PMLOADDERIVEDCONFIG(3)
2
3
4

NAME

6       pmLoadDerivedConfig - load derived metric definitions from files
7

C SYNOPSIS

9       #include <pcp/pmapi.h>
10
11       int pmLoadDerivedConfig(char *path);
12
13       cc ... -lpcp
14

DESCRIPTION

16       Derived  metrics  may  be used to extend the available metrics with new
17       (derived) metrics using simple arithmetic expressions.  The definitions
18       of these metrics can be persisted and loaded programatically by monitor
19       tools using pmLoadDerivedConfig.
20
21       The path parameter defines a  colon  separated  list  of  files  and/or
22       directories  (the  syntax  is  the  same  as for the $PATH variable for
23       sh(1)), from which derived metric specifications  are  to  be  sourced.
24       The  path components are expanded into a list of files as follows: if a
25       component is a file, then that file is added to the  list,  else  if  a
26       component  is  a  directory then recursive descent is used to enumerate
27       all files below that directory and these are added to the  list.   Each
28       file  in  the  resulting  list is parsed in order, and according to the
29       derived metrics syntax described below.
30
31       Each line of the file(s) identified by path is either  a  comment  line
32       (with  a ``#'' in the first position of the line) or the declaration of
33       a derived performance metric, specified as:
34
35       * the name of the derived metric, using the same ``dot notation''  syn‐
36         tax  that  is  used  for PCP performance metrics, see PCPIntro(1) and
37         PMNS(5).
38
39       * an equals sign (``='')
40
41       * a valid expression for a derived metric, as described in  pmRegister‐
42         Derived(3).
43
44       White space is ignored in the lines.
45
46       For  each  line  containing  a  derived  metric definition, pmRegister‐
47       Derived(3) is called to register the new derived metric.
48
49       Because pmLoadDerivedConfig may process many files, each of  which  may
50       contain  many derived metric specifications, it is not possible to pro‐
51       vide very specific error status  on  return.   Hence  the  result  from
52       pmLoadDerivedConfig  will be the number of derived metrics successfully
53       loaded from files on the given path.  Catastrophic errors such  as  not
54       being  able  to  open  one of the files on the given path will cause an
55       immediate return with a negative return value that  can  be  passed  to
56       pmErrStr(3) to obtain the associated error message.
57
58       When  errors are encountered in the derived metric specifications diag‐
59       nostic messages are generated by pmRegisterDerived(3) and displayed via
60       pmprintf(3).
61

EXAMPLE

63       # sample derived metric definitions
64       bad_in_pkts = network.interface.in.errors + network.interface.in.drops
65       # note the following would need to be on a single line ...
66       disk.dev.read_pct = 100 * delta(disk.dev.read) /
67                   (delta(disk.dev.read) + delta(disk.dev.write))
68

SEE ALSO

70       sh(1),  PCPIntro(1),  PMAPI(3),  pmRegisterDerived(3),  pmprintf(3) and
71       PMNS(5).
72
73
74
75Performance Co-Pilot                                    PMLOADDERIVEDCONFIG(3)
Impressum