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