pmLoadDerivedConfig(3)

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       * an equals sign (``='')
39       * a valid expression for a derived metric, as described in  pmRegister‐
40         Derived(3).
41
42       For  each  line  containing  a  derived  metric definition, pmRegister‐
43       Derived(3) is called to register the new derived metric.
44
45       Once a derived metric has been declared, it may be assigned  additional
46       attributes with a line of the form:
47
48       * the name of the derived metric,
49       * a left parenthesis, an attribute type and a right parenthesis,
50       * an equals sign (``=''),
51       * an attribute value.
52
53       Currently,  attribute  type may be either oneline or helptext to desig‐
54       nate the ``one line'' or expanded help text to be associated  with  the
55       derived metric, see pmLookupText(3).
56
57       The  attribute  value  may be either arbitrary text following the ``=''
58       and ending at the end of the line, else a  string  enclosed  in  either
59       single  quotes  (')  or  double  quotes  (").   In the latter case, the
60       attribute value may span multiple lines, and a simple escape  mechanism
61       is  supported,  namely  for  any character ``x'', ``\x'' is replaced by
62       ``x'' (this allows quotes to be escaped within a string, for  example),
63       and there is a special case when the ``\'' comes at the end of the line
64       in which case the following newline is not included  in  the  attribute
65       value.
66
67       Outside  of  attribute values, white space is ignored in the lines, and
68       blank lines are ignored altogether.
69
70       Because pmLoadDerivedConfig may process many files, each of  which  may
71       contain  many derived metric specifications, it is not possible to pro‐
72       vide a specific error status on return.  Hence the result from  pmLoad‐
73       DerivedConfig will be the number of derived metrics successfully loaded
74       from files on the given path.  Catastrophic errors such  as  not  being
75       able to open one of the files on the given path will cause an immediate
76       return with a negative return value that can be passed  to  pmErrStr(3)
77       to obtain the associated error message.
78
79       When  errors are encountered in the derived metric specifications diag‐
80       nostic messages are generated by pmRegisterDerived(3) and displayed via
81       pmprintf(3).
82

EXAMPLE

84       # sample derived metric definitions
85       bad_in_pkts = network.interface.in.errors + network.interface.in.drops
86       # note the following would need to be on a single line ...
87       disk.dev.read_pct = 100 * delta(disk.dev.read) /
88                   (delta(disk.dev.read) + delta(disk.dev.write))
89       disk.dev.read_pct(oneline) = percentage of disk reads
90       disk.dev.read_pct(helptext) = '\
91       Percentage of disk reads compared to the total number of
92       disk reads and disk writes.'
93

NAME

C SYNOPSIS

DESCRIPTION

EXAMPLE

SEE ALSO