pmloadderivedconfig(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON

PMLOADDERIVEDCONFIG(3)   Library Functions Manual  PMLOADDERIVEDCONFIG(3)

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 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         top

       # 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         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2025-08-11.  (At that time, the date of the most recent commit
       that was found in the repository was 2025-08-11.)  If you discover
       any rendering problems in this HTML version 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 manual page), send a
       mail to man-pages@man7.org

Performance Co-Pilot                               PMLOADDERIVEDCONFIG(3)

Pages that refer to this page: pcp2elasticsearch(1)pcp2graphite(1)pcp2influxdb(1)pcp2json(1)pcp2openmetrics(1)pcp2spark(1)pcp2template(1)pcp2xlsx(1)pcp2xml(1)pcp2zabbix(1)pcpintro(1)pminfo(1)pmprobe(1)pmrep(1)pmaddderived(3)pmaddderivedtext(3)pmgetderivedcontrol(3)pmreconnectcontext(3)pmregisterderived(3)zbxpcp(3)