1PMADDDERIVED(3) Library Functions Manual PMADDDERIVED(3)
2
6 pmAddDerived, pmAddDerivedMetric - register a per-context derived met‐
7 ric name and definition
8
10 #include <pcp/pmapi.h>
11 char *pmAddDerived(char *name, char *expr);
13 int pmAddDerivedMetric(char *name, char *expr, char **errmsg);
14 cc ... -lpcp
16
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 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 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 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 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 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 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 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
55 On success, pmAddDerived returns NULL.
56 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 pmAddDerivedMetric returns 0 and errmsg is undefined if the parsing is
64 successful.
65 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 The position indicator line may be followed by an additional diagnostic
76 line describing the nature of the error, when available.
77 In the case of an error, the caller is responsible for calling free(3)
79 to release the space allocated for errmsg.
80
82 PCPIntro(1), PMAPI(3), pmDerivedErrStr(3), pmDestroyContext(3), pmLoad‐
83 DerivedConfig(3), pmNewContext(3), pmRegisterDerived(3), pmRegister‐
84 DerivedMetric(3) and PMNS(5).
85Performance Co-Pilot PMADDDERIVED(3)