1PMADDDERIVED(3)            Library Functions Manual            PMADDDERIVED(3)
2
3
4

NAME

6       pmAddDerived, pmAddDerivedMetric  - register a per-context derived met‐
7       ric name and definition
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       char *pmAddDerived(char *name, char *expr);
13       int pmAddDerivedMetric(char *name, char *expr, char **errmsg);
14
15       cc ... -lpcp
16

DESCRIPTION

18       Derived metrics provide a way of extending the Performance Metrics Name
19       Space  (PMNS)  with  new  metrics  defined at the PCP client-side using
20       expressions over the existing performance metrics.
21
22       The pmAddDerived and pmAddDerivedMetric routines may be used to  create
23       per-context  derived  metrics,  and  can only be used after the current
24       PMAPI context has been created with pmNewContext(3).
25
26       Per-context derived metrics are similar in all aspects except scope  to
27       global  derived  metrics.  The latter are defined across all PMAPI con‐
28       texts and are created with the associated pmRegisterDerived(3),  pmReg‐
29       isterDerivedMetric(3) and pmRegisterLoadConfig(3) routines.
30
31       The  arguments  to  pmAddDerived are the name of the new derived metric
32       and expr is an expression defining how the values  of  name  should  be
33       computed.
34
35       pmAddDerivedMetric  is  the exact functional equivalent to pmAddDerived
36       except that it provides a simplified model of error handling,  where  a
37       formatted message is returned via the errmsg parameter.
38
39       Refer  to  the pmRegisterDerived(3) man page for a complete description
40       of the syntactic rules for name, the syntactic and semantic  rules  for
41       expr,  return values and the associated error reporting mechanisms, and
42       the expression evaluation rules.
43
44       Note that for per-context derived metrics, all syntactic  and  semantic
45       checks  are performed at the time pmAddDerived or pmAddDerivedMetric is
46       called.  This is different to global derived metrics where the semantic
47       checks  are  delayed  until the metric is used in a specific PMAPI con‐
48       text.
49
50       There is no ``unregister'' method, so  once  registered  a  per-context
51       derived  metric  persists  for the life of the PMAPI context, but it is
52       destroyed as a side-effect of pmDestroyContext(3).
53

DIAGNOSTICS

55       On success, pmAddDerived returns NULL.
56
57       If a syntactic error is  found  at  the  time  of  calling,  the  value
58       returned  by  pmAddDerived  is a pointer into expr indicating where the
59       error was found.  To identify  what  the  error  was,  the  application
60       should  call  pmDerivedErrStr(3)  to  retrieve the corresponding parser
61       error message.
62
63       pmAddDerivedMetric returns 0 and errmsg is undefined if the parsing  is
64       successful.
65
66       If the given expr does not conform to the required syntax pmAddDerived‐
67       Metric returns -1 and a dynamically allocated error message  string  in
68       errmsg.   The  error  message is terminated with a newline and includes
69       both the input name and expr, along with an indicator of  the  position
70       at which the error was detected.  e.g.
71                 Error: pmAddDerivedMetric("my.disk.rates", ...) syntax error
72                 4rat(disk.dev.read)
73                     ^
74
75       The position indicator line may be followed by an additional diagnostic
76       line describing the nature of the error, when available.
77
78       In the case of an error, the caller is responsible for calling  free(3)
79       to release the space allocated for errmsg.
80

SEE ALSO

82       PCPIntro(1), PMAPI(3), pmDerivedErrStr(3), pmDestroyContext(3), pmLoad‐
83       DerivedConfig(3),  pmNewContext(3),  pmRegisterDerived(3),  pmRegister‐
84       DerivedMetric(3) and PMNS(5).
85
86
87
88Performance Co-Pilot                                           PMADDDERIVED(3)