NAME

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

C SYNOPSIS

       #include <pcp/pmapi.h>

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

       cc ... -lpcp

DESCRIPTION

       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  pmRegisterLoadConfig(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

       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

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