pmaddderived(3) — Linux manual page

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

PMADDDERIVED(3)         Library Functions Manual         PMADDDERIVED(3)

NAME         top

       pmAddDerived, pmAddDerivedMetric  - register a per-context
       derived metric name and definition

C SYNOPSIS         top

       #include <pcp/pmapi.h>

       char *pmAddDerived(char *name, char *expr);
       int pmAddDerivedMetric(char *name, char *expr, char **errmsg);

       cc ... -lpcp

DESCRIPTION         top

       Derived metrics provide a way of extending the Performance
       Metrics Name Space (PMNS) with new metrics defined at the PCP
       client-side using expressions over the existing performance
       metrics.

       The pmAddDerived and pmAddDerivedMetric routines may be used to
       create per-context derived metrics, and can only be used after
       the current PMAPI context has been created with pmNewContext(3).

       Per-context derived metrics are similar in all aspects except
       scope to global derived metrics.  The latter are defined across
       all PMAPI contexts and are created with the associated
       pmRegisterDerived(3), pmRegisterDerivedMetric(3) and
       pmLoadDerivedConfig(3) routines.

       The arguments to pmAddDerived are the name of the new derived
       metric and expr is an expression defining how the values of name
       should be computed.

       pmAddDerivedMetric is the exact functional equivalent to
       pmAddDerived except that it provides a simplified model of error
       handling, where a formatted message is returned via the errmsg
       parameter.

       Refer to the pmRegisterDerived(3) man page for a complete
       description of the syntactic rules for name, the syntactic and
       semantic rules for expr, return values and the associated error
       reporting mechanisms, and the expression evaluation rules.

       Note that for per-context derived metrics, all syntactic and
       semantic checks are performed at the time pmAddDerived or
       pmAddDerivedMetric is called.  This is different to global
       derived metrics where the semantic checks are delayed until the
       metric is used in a specific PMAPI context.

       There is no ``unregister'' method, so once registered a per-
       context derived metric persists for the life of the PMAPI
       context, but it is destroyed as a side-effect of
       pmDestroyContext(3).

DIAGNOSTICS         top

       On success, pmAddDerived returns NULL.

       If a syntactic error is found at the time of calling, the value
       returned by pmAddDerived is a pointer into expr indicating where
       the error was found.  To identify what the error was, the
       application should call pmDerivedErrStr(3) to retrieve the
       corresponding parser error message.

       pmAddDerivedMetric returns 0 and errmsg is undefined if the
       parsing is successful.

       If the given expr does not conform to the required syntax
       pmAddDerivedMetric returns -1 and a dynamically allocated error
       message string in errmsg.  The error message is terminated with a
       newline and includes both the input name and expr, along with an
       indicator of the position at which the error was detected.  e.g.
                 Error: pmAddDerivedMetric("my.disk.rates", ...) syntax
                 error
                 4rat(disk.dev.read)
                     ^

       The position indicator line may be followed by an additional
       diagnostic line describing the nature of the error, when
       available.

       In the case of an error, the caller is responsible for calling
       free(3) to release the space allocated for errmsg.

SEE ALSO         top

       PCPIntro(1), PMAPI(3), pmDerivedErrStr(3), pmDestroyContext(3),
       pmLoadDerivedConfig(3), pmNewContext(3), pmRegisterDerived(3),
       pmRegisterDerivedMetric(3) and PMNS(5).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information 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 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  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                                     PMADDDERIVED(3)

Pages that refer to this page: pminfo(1)pmaddderivedtext(3)pmgetderivedcontrol(3)pmregisterderived(3)pmwebapi(3)