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

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

SEE ALSO

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

Performance Co-Pilot                                                                      PMLOADDERIVEDCONFIG(3)