NAME         top

       pmLoadDerivedConfig - load derived metric definitions from files

C SYNOPSIS         top

       #include <pcp/pmapi.h>

       int pmLoadDerivedConfig(char *path);

       cc ... -lpcp

DESCRIPTION         top

       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

       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         top

       # sample derived metric definitions
       bad_in_pkts = +
       # note the following would need to be on a single line ... = 100 * delta( /
                   (delta( + delta(

SEE ALSO         top

       sh(1), PCPIntro(1), PMAPI(3), pmRegisterDerived(3), pmprintf(3) and

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2017-09-15.  If you discover any rendering problems in this HTML ver‐
       sion of the page, or you believe there is a better or more up-to-date
       source for the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original man‐
       ual page), send a mail to

Performance Co-Pilot                                  PMLOADDERIVEDCONFIG(3)

Pages that refer to this page: pcpintro(1)pminfo(1)pmrep(1)pmreconnectcontext(3)pmregisterderived(3)zbxpcp(3)