NAME

       pmLoadDerivedConfig - load derived metric definitions from files

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmLoadDerivedConfig(char *path);

       cc ... -lpcp

DESCRIPTION

       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).

       White space is ignored in the lines.

       For each line containing a derived metric definition, pmRegisterDerived(3)  is  called  to
       register the new derived metric.

       Because pmLoadDerivedConfig may process many files, each of which may contain many derived
       metric specifications, it is not possible to provide very 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).

EXAMPLE

       # 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))

SEE ALSO

       sh(1), PCPIntro(1), PMAPI(3), pmRegisterDerived(3), pmprintf(3) and pmns(5).