# pmloadderivedconfig

## 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 program‐
           matically 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  be‐
           low.
    
           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  dec‐
           laration 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 addi‐
           tional 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 giv‐
           en _path_ will cause an immediate return with a negative return val‐
           ue that can be passed to pmErrStr(3) to obtain the associated er‐
           ror message.
    
           When errors are encountered in the derived metric specifications
           diagnostic messages are generated by pmRegisterDerived(3) and dis‐
           played 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.'
    


* * *