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