pmLoadDerivedConfig - load derived metric definitions from files
#include <pcp/pmapi.h>
int pmLoadDerivedConfig(char *
path);
cc ... -lpcp
Derived metrics may be used to extend the available metrics with new (derived)
metrics using simple arithmetic expressions. The definitions of these metrics
can be persisted and loaded programatically by monitor tools using
pmLoadDerivedConfig.
The
path parameter defines a colon separated list of files and/or
directories (the syntax is the same as for the
$PATH variable for
sh(1)), from which derived metric specifications are to be sourced. The
path components are expanded into a list of files as follows: if a
component is a file, then that file is added to the list, else if a component
is a directory then recursive descent is used to enumerate all files below
that directory and these are added to the list. Each file in the resulting
list is parsed in order, and according to the derived metrics syntax described
below.
Each line of the file(s) identified by
path is either a comment line
(with a ``#'' in the first position of the line) or the declaration of a
derived performance metric, specified as:
- *
- the name of the derived metric, using the same ``dot
notation'' syntax that is used for PCP performance metrics, see
PCPIntro(1) and PMNS(5).
- *
- an equals sign (``='')
- *
- a valid expression for a derived metric, as described in
pmRegisterDerived(3).
For each line containing a derived metric definition,
pmRegisterDerived(3) is called to register the new derived metric.
Once a derived metric has been declared, it may be assigned additional
attributes with a line of the form:
- *
- the name of the derived metric,
- *
- a left parenthesis, an attribute type and a
right parenthesis,
- *
- an equals sign (``=''),
- *
- an attribute value.
Currently,
attribute type may be either
oneline or
helptext to designate the ``one line'' or expanded help text to be
associated with the derived metric, see
pmLookupText(3).
The
attribute value may be either arbitrary text following the
``='' and ending at the end of the line, else a string enclosed in either
single quotes (') or double quotes ("). In the latter case, the
attribute value may span multiple lines, and a simple escape
mechanism is supported, namely for any character ``x'', ``\x'' is replaced by
``x'' (this allows quotes to be escaped within a string, for example), and
there is a special case when the ``\'' comes at the end of the line in which
case the following newline is not included in the
attribute
value.
Outside of
attribute values, white space is ignored in the lines,
and blank lines are ignored altogether.
Because
pmLoadDerivedConfig may process many files, each of which may
contain many derived metric specifications, it is not possible to provide a
specific error status on return. Hence the result from
pmLoadDerivedConfig will be the number of derived metrics successfully
loaded from files on the given
path. Catastrophic errors such as not
being able to open one of the files on the given
path will cause an
immediate return with a negative return value that can be passed to
pmErrStr(3) to obtain the associated error message.
When errors are encountered in the derived metric specifications diagnostic
messages are generated by
pmRegisterDerived(3) and displayed via
pmprintf(3).
# sample derived metric definitions
bad_in_pkts = network.interface.in.errors + network.interface.in.drops
# note the following would need to be on a single line ...
disk.dev.read_pct = 100 * delta(disk.dev.read) /
(delta(disk.dev.read) + delta(disk.dev.write))
disk.dev.read_pct(oneline) = percentage of disk reads
disk.dev.read_pct(helptext) = '\
Percentage of disk reads compared to the total number of
disk reads and disk writes.'
sh(1),
PCPIntro(1),
PMAPI(3),
pmLookupText(3),
pmRegisterDerived(3),
pmprintf(3) and
PMNS(5).