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 ex‐
20       pressions 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 de‐
51       rived  metric persists for the life of the PMAPI context, but it is de‐
52       stroyed 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  re‐
58       turned  by pmAddDerived is a pointer into expr indicating where the er‐
59       ror was found.  To identify what the error was, the application  should
60       call pmDerivedErrStr(3) to retrieve the corresponding parser error mes‐
61       sage.
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)
Impressum