1PMLOADDERIVEDCONFIG(3) Library Functions Manual PMLOADDERIVEDCONFIG(3)
2
6 pmLoadDerivedConfig - load derived metric definitions from files
7
9 #include <pcp/pmapi.h>
10 int pmLoadDerivedConfig(char *path);
12 cc ... -lpcp
14
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 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 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 * 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 For each line containing a derived metric definition, pmRegister‐
43 Derived(3) is called to register the new derived metric.
44 Once a derived metric has been declared, it may be assigned additional
46 attributes with a line of the form:
47 * 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 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 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 Outside of attribute values, white space is ignored in the lines, and
68 blank lines are ignored altogether.
69 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 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
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
95 sh(1), PCPIntro(1), PMAPI(3), pmLookupText(3), pmRegisterDerived(3),
96 pmprintf(3) and PMNS(5).
97Performance Co-Pilot PMLOADDERIVEDCONFIG(3)