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).