1PMREGISTERDERIVED(3) Library Functions Manual PMREGISTERDERIVED(3)
2
6 pmRegisterDerived, pmRegisterDerivedMetric - register a global derived
7 metric name and definition
8
10 #include <pcp/pmapi.h>
11 char *pmRegisterDerived(char *name, char *expr);
13 int pmRegisterDerivedMetric(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 ex‐
20 pressions over the existing performance metrics.
21 Typical uses would be to aggregate a number of similar metrics to pro‐
23 vide a higher-level summary metric or to support the ``delta V over
24 delta V'' class of metrics that are not possible in the base data se‐
25 mantics of PCP. An example of the latter class would be the average
26 I/O size, defined as
27 delta(disk.dev.total_bytes) / delta(disk.dev.total)
28 where both of the disk.dev metrics are counters, and what is required
29 is to sample both metrics, compute the difference between the current
30 and previous values and then calculate the ratio of these differences.
31 The arguments to pmRegisterDerived are the name of the new derived met‐
33 ric and expr is an expression defining how the values of name should be
34 computed.
35 pmRegisterDerivedMetric is the exact functional equivalent to pmRegis‐
37 terDerived except that it provides a simplified model of error han‐
38 dling, where a formatted message is returned via the errmsg parameter.
39 Syntactic checking is performed at the time pmRegisterDerived is
41 called, but semantic checking is deferred until each new PMAPI context
42 is created with pmNewContext(3) or re-established with pmReconnectCon‐
43 text(3), at which time the PMNS and metadata is available to allow se‐
44 mantic checking and the metadata of the derived metrics to be deter‐
45 mined.
46 If pmRegisterDerived is called after one or more PMAPI contexts has
48 been opened, then the newly registered metrics will be avaiable in
49 those contexts, however the more normal use would be to make all calls
50 to pmRegisterDerived (possibly via pmLoadDerivedConfig(3)) or pmRegis‐
51 terDerivedMetric before calling pmNewContext(3).
52 All of the defined global derived metrics are available in all PMAPI
54 contexts.
55 It is also possible to define per-context derived metrics once a PMAPI
57 context has been establised. These derived metrics are private to the
58 context in which they are defined using the allied routines pmAd‐
59 dDerived(3) and pmAddDerivedMetric(3).
60 name should follow the syntactic rules for the names of performance
62 metrics, namely one or more components separated with a dot (``.''),
63 and each component must begin with an alphabetic followed by zero or
64 more characters drawn from the alphabetics, numerics and underscore
65 (``_''). For more details, refer to PCPIntro(1) and PMNS(5).
66 name must be unique across all derived metrics and should not match the
68 name of any regular metric in the PMNS. It is acceptable for name to
69 share some part of its prefix with an existing subtree of the PMNS,
70 e.g. the average I/O size metric above could be named disk.dev.avgsz
71 which would place it amongst the other disk.dev metrics in the PMNS.
72 Alternatively, derived metrics could populate their own subtree of the
73 PMNS, e.g. the average I/O size metric above could be named my.sum‐
74 mary.disk.avgsz.
75 The expression expr follows these syntactic rules:
77 * Terminal elements are either names of existing metrics or numeric
79 constants. Recursive definitions are not allowed, so only the names
80 of regular metrics (not other derived metrics) may be used. Numeric
81 constants are either integers constrained to the precision of 32-bit
82 unsigned integers or double precision floating point numbers.
83 * The usual binary arithmetic operators are supported, namely addition
85 (``+''), subtraction (``-''), multiplication (``*'') and division
86 (``/'') with the normal precedence rules where multiplication and di‐
87 vision have higher precedence than addition and subtraction, so a+b*c
88 is evaluated as a+(b*c).
89 * Unary negation may be used, e.g. -3*some.metric.
91 * C-style relational operators are supported, namely ``<'', ``<='',
93 ``=='', ``>='', ``>'' and ``!=''. Relational expresssions return a
94 value as a 32-bit unsigned number being 0 for false and 1 for true.
95 The expected operator precedence rules apply, so arithmetic operators
96 have higher precedence than relational operators, and a-b>c+d is
97 evaluated as (a-b)>(c+d). All the relational operators have equal
98 precedence, so the (slightly odd) expression involving consecutive
99 relational operators a>b!=c is evaluated as (a>b)!=c.
100 * C-style boolean operators are supported, namely and (``&&'') and or
102 (``||''). Boolean expresssions return a value as a 32-bit unsigned
103 number being 0 for false and 1 for true. The expected operator
104 precedence rules apply, so relational operators have higher prece‐
105 dence than boolean operators, and a>b*c&&d<=e+f is evaluated as
106 (a>(b*c))&&(d<=(e+f)). Both the boolean operators have equal prece‐
107 dence, so the expression involving consecutive boolean operators
108 a>=b||b>c&&d!=e||f>g is evaluated as
109 (((a>=b)||(b>c))&&(d!=e))||(f>g).
110 * Additionally, the ``!'' operator may be used to negate a boolean or
112 relational expression, returning a value as a 32-bit unsigned number
113 being 0 for false and 1 for true. The expected operator precedence
114 rules apply, so boolean (and relational) operators have higher prece‐
115 dence than boolean negation, and !a>b||c<d is evaluated as
116 !((a>b)||(c<d)), while !a<b+c is evaluated as !(a<(b+c)).
117 * C-style ternary conditional expressions are supported. In general
119 terms the expression check ? foo : bar is evaluated as foo (the
120 ``true'' operand) if check (the ``guard'') is true, else the expres‐
121 sion evaluates to bar (the ``false'' operand). Some special semantic
122 rules apply to the ``guard'' expression and the other two operand ex‐
123 pressions:
124 (a) Each expression may involve a singular value or a set of values
125 (when the expression involves one or more metrics with an in‐
126 stance domain).
127 (b) All expressions with a set of values must be defined over the
128 same instance domain.
129 (c) Both operand expressions must have the same metadata, so the same
130 metric type, semantics and units (dimension and scale).
131 (d) The ``guard'' expression must have an aritmetic or relational or
132 boolean value, so that it can be evaluated as 0 for false, else
133 true.
134 (e) If the ``guard'' expression has a singular value and one or more
135 of the other operand expressions involves an instance domain, the
136 ``guard'' applies to all instances.
137 (f) If the ``guard'' expression has a set of values and one or more
138 of the other operand expressions involves an instance domain, the
139 ``guard'' is evaluated once for each instance (there must be one
140 instance domain as per rule (b) above).
141 (g) If one of the operand expressions has a singular value and the
142 other has a set of values, and the singular value is selected
143 based on the evaluation of the ``guard'', then the result is a
144 set of values (all the same) with instance enumeration being
145 taken from the other operand expression. For example in the ex‐
146 pression: foo ? scalar : set, if foo is true, then the result is
147 a set of values (all having the same value, scalar) over the in‐
148 stance domain of set.
149 * Selection of a single instance can be specified by the construct
151 ``[instance_name]'' which may be appended to a metric name or a
152 parenthesized expression. For example:
153 fw.bytes = network.interface.in.bytes[eth1] + \
154 network.interface.out.bytes[eth1]
155 or (equivalently):
156 fw.bytes = (network.interface.in.bytes + \
157 network.interface.out.bytes)[eth1]
158 All characters between the ``['' and ``]'' are considered to be part
160 of the (external) instance name, so be careful to avoid any spurious
161 white space. A backslash may be used as an escape prefix in the (un‐
162 likely) event that the external instance name contains a ``]''.
163 * Numeric constants can also be specified using the mkconst() construc‐
165 tor which takes a number of arguments: the first is a numeric con‐
166 stant (either integer or floating point), then follow one or more pa‐
167 rameters of the form tag=value or tag= where the allowed values of
168 tag and value are as follows:
169 ┌──────────┬───────────────────────────────────────────────┐
171 │ tag │ value │
172 ├──────────┼───────────────────────────────────────────────┤
173 │type │ one of the numeric metric types from │
174 │ │ <pcp/pmapi.h>, stripped of the PM_TYPE_ pre‐ │
175 │ │ fix, so 32, U32, 64, U64, FLOAT or DOUBLE. │
176 ├──────────┼───────────────────────────────────────────────┤
177 │semantics │ one of the semantic types from <pcp/pmapi.h>, │
178 │ │ stripped of the PM_SEM_ prefix, so COUNTER, │
179 │ │ INSTANT or DISCRETE. │
180 ├──────────┼───────────────────────────────────────────────┤
181 │units │ a specification of dimension and scale (to‐ │
182 │ │ gether forming the units), in the syntax ac‐ │
183 │ │ cepted by pmParseUnitsStr(3). │
184 └──────────┴───────────────────────────────────────────────┘
185 The value may optionally be enclosed in double quotes, and may appear
186 in any mix of upper and/or lower case. The tag must be in lower case
187 as shown in the table above.
188 This is most useful when the expression semantics require matching
190 type and/or semantics and/or units for operands, e.g.
191 idle = mem.util.free > mkconst(10485760, units=Kbyte)
192 avg_io_size = delta(disk.dev.total) == 0 ? \
193 -mkconst(1.0, semantics=instant, units="kbyte / count") : \
194 delta(disk.dev.total_bytes) / delta(disk.dev.total)
195 * Expressions may be rescaled using the rescale function that takes two
197 arguments. The first is an arithmetic expression to be rescaled, and
198 the second is the desired units after rescaling that is a string
199 value in the syntax accepted by pmParseUnitsStr(3). For example:
200 rescale(network.interface.total.bytes, "Mbytes/hour")
201 The expression and the desired units must both have the same dimen‐
203 sion, e.g Space=1, Time=-1 and Count=0 in the example above.
204 * The following unary functions operate on a single performance metric
206 and return one or more values. For all functions (except count(),
207 defined() and instant()), the type of the operand metric must be
208 arithmetic (integer of various sizes and signedness, float or dou‐
209 ble).
210 ┌───────────┬───────────────────────────────────────────────┐
212 │ Function │ Value │
213 ├───────────┼───────────────────────────────────────────────┤
214 │avg(x) │ A singular instance being the average value │
215 │ │ across all instances for the metric x. │
216 ├───────────┼───────────────────────────────────────────────┤
217 │count(x) │ A singular instance being the count of the │
218 │ │ number of instances for the metric x. As a │
219 │ │ special case, if fetching the metric x re‐ │
220 │ │ turns an error, then count(x) will be 0. │
221 ├───────────┼───────────────────────────────────────────────┤
222 │defined(x) │ A boolean value that is true (``1'') if the │
223 │ │ metric x is defined in the PMNS, else false │
224 │ │ (``0''). The function is evaluated when a │
225 │ │ new PMAPI context is created with pmNewCon‐ │
226 │ │ text(3) or re-established with pmReconnect‐ │
227 │ │ Context(3). So any subsequent changes to the │
228 │ │ PMNS after the PMAPI context has been estab‐ │
229 │ │ lished will not change the value of this │
230 │ │ function in the expression evaluation. │
231 ├───────────┼───────────────────────────────────────────────┤
232 │delta(x) │ Returns the difference in values for the met‐ │
233 │ │ ric x between one call to pmFetch(3) and the │
234 │ │ next. There is one value in the result for │
235 │ │ each instance that appears in both the cur‐ │
236 │ │ rent and the previous sample. If the metric │
237 │ │ x is unsigned, then the type of the result is │
238 │ │ converted to ensure as much precision as pos‐ │
239 │ │ sible can be retained, so if the metric x has │
240 │ │ type PM_TYPE_U32 then the result is of type │
241 │ │ PM_TYPE_64, else if the metric x has type │
242 │ │ PM_TYPE_U64 then the result is of type │
243 │ │ PM_TYPE_DOUBLE. Otherwise the type of the │
244 │ │ result is the same as the type of the metric │
245 │ │ x. │
246 ├───────────┼───────────────────────────────────────────────┤
247 │rate(x) │ Returns the difference in values for the met‐ │
248 │ │ ric x between one call to pmFetch(3) and the │
249 │ │ next divided by the elapsed time between the │
250 │ │ calls to pmFetch(3). The semantics of the │
251 │ │ derived metric are based on the semantics of │
252 │ │ the metric x with the dimension in the time │
253 │ │ domain decreased by one and scaling if re‐ │
254 │ │ quired in the time utilization case where the │
255 │ │ operand is in units of time, and the derived │
256 │ │ metric is unitless. This mimics the rate │
257 │ │ conversion applied to counter metrics by │
258 │ │ tools such as pmval(1), pmie(1) and pm‐ │
259 │ │ chart(1). There is one value in the result │
260 │ │ for each instance that appears in both the │
261 │ │ current and the previous sample. │
262 ├───────────┼───────────────────────────────────────────────┤
263 │instant(x) │ Returns the current value of the metric x, │
264 │ │ even it has the semantics of a counter, i.e. │
265 │ │ PM_SEM_COUNTER. The semantics of the derived │
266 │ │ metric are based on the semantics of the met‐ │
267 │ │ ric x; if x has semantics PM_SEM_COUNTER, the │
268 │ │ semantics of instant(x) is PM_SEM_INSTANT, │
269 │ │ otherwise the semantics of the derived metric │
270 │ │ is the same as the semantics of the metric x. │
271 ├───────────┼───────────────────────────────────────────────┤
272 │max(x) │ A singular instance being the maximum value │
273 │ │ across all instances for the metric x. │
274 ├───────────┼───────────────────────────────────────────────┤
275 │min(x) │ A singular instance being the minimum value │
276 │ │ across all instances for the metric x. │
277 ├───────────┼───────────────────────────────────────────────┤
278 │sum(x) │ A singular instance being the sum of the val‐ │
279 │ │ ues across all instances for the metric x. │
280 └───────────┴───────────────────────────────────────────────┘
281 * The matchinst function may be used to select a subset of the in‐
282 stances from an instance domain for a metric or expression. The
283 function takes two arguments:
284 (a) A instance filter that consists of an optional negation operator
285 ``!'' followed by a regular expression delimited by ``/'' charac‐
286 ters. The regular expression follows the POSIX Extended Regular
287 Expression syntax as described in regex(3). Backslashes may be
288 used as escape prefixes, but double backslash is required to es‐
289 cape any regular expression special characters, e.g. for the (ex‐
290 tremely unlikely) case of wanting to match instance names like
291 ``some*text/other[text]'' a regular expression of the form
292 /some\\*text\/other\\[text]/ would be required. If present, the
293 negation operator reverses the sense of the filtering, so all in‐
294 stances not matching the regular expression will be selected.
295 (b) A metric or expression that must be defined over an instance do‐
296 main.
297 For example, the following expression will have values for the metric
299 network.interface.in.bytes for all network interfaces except the
300 loopback and virtual bridge devices:
301 matchinst(!/^(lo)|(vbir)/, network.interface.in.bytes)
302 * The scalar function may be used convert a metric or expression de‐
304 fined over an instance domain into a scalar value that can be used in
305 other expressions. For example:
306 net.in.bytes = scalar(network.interface.in.bytes[eth0]) + \
307 scalar(network.interface.in.bytes[eth1])
308 The instance domain is removed from the metadata for the result and
310 the instance identifier is removed from the value during fetching.
311 If the metric or expression involves more than one instance then the
313 result is formed by picking the first instance - this is arbitrary
314 and implies the scalar function should only be used for metrics or
315 expressions that are expected to contain zero or one instances, e.g.
316 the construct ``[instance_name]'' or the matchinst function with a
317 pattern that matches at most one instance.
318 * Parenthesis may be used for explicit grouping.
320 * Lines beginning with ``#'' are treated as comments and ignored.
322 * White space is ignored.
324
326 There are a number of conversions required to determine the metadata
327 for a derived metric and to ensure the semantics of the expressions are
328 sound.
329 In an arithmetic expression or a relational expression, if the seman‐
331 tics of both operands is not a counter (i.e. PM_SEM_INSTANT or
332 PM_SEM_DISCRETE) then the result will have semantics PM_SEM_INSTANT un‐
333 less both operands are PM_SEM_DISCRETE in which case the result is also
334 PM_SEM_DISCRETE.
335 For an arithmetic expression, the dimension of each operand must be the
337 same. For a relational expression, the dimension of each operand must
338 be the same, except that numeric constants (with no dimension) are al‐
339 lowed, e.g. in the expression network.interface.in.drops > 0 .
340 To prevent arbitrary and non-sensical combinations some restrictions
342 apply to expressions that combine metrics with counter semantics to
343 produce a result with counter semantics. For an arithmetic expression,
344 if both operands have the semantics of a counter, then only addition or
345 subtraction is allowed, or if the left operand is a counter and the
346 right operand is not, then only multiplication or division are allowed,
347 or if the left operand is not a counter and the right operand is a
348 counter, then only multiplication is allowed.
349 Because relational expressions use the current value only and produce a
351 result that is not a counter, either or both operands of a relational
352 expression may be counters.
353 The mapping of the pmUnits of the metadata uses the following rules:
355 * If both operands have a dimension of Count and the scales are not the
357 same, use the larger scale and convert the values of the operand with
358 the smaller scale.
359 * If both operands have a dimension of Time and the scales are not the
361 same, use the larger scale and convert the values of the operand with
362 the smaller scale.
363 * If both operands have a dimension of Space and the scales are not the
365 same, use the larger scale and convert the values of the operand with
366 the smaller scale.
367 * For addition and subtraction all dimensions for each of the operands
369 and result are identical.
370 * For multiplication, the dimensions of the result are the sum of the
372 dimensions of the operands.
373 * For division, the dimensions of the result are the difference of the
375 dimensions of the operands.
376 Scale conversion involves division if the dimension is positive else
378 multiplication if the dimension is negative. If scale conversion is ap‐
379 plied to either of the operands, the result is promoted to type
380 PM_TYPE_DOUBLE.
381 Putting all of this together in an example, consider the derived metric
383 defined as follows:
384 x = network.interface.speed - delta(network.interface.in.bytes) /
385 delta(sample.milliseconds)
386 The type, dimension and scale settings would propagate up the expres‐
387 sion tree as follows.
388 ┌────────────────────────┬────────┬───────────────┬─────────────────┐
390 │ Expression │ Type │ Dimension & │ Scale Factor(s) │
391 │ │ │ Scale │ │
392 ├────────────────────────┼────────┼───────────────┼─────────────────┤
393 │sample.milliseconds │ DOUBLE │ millisec │ │
394 │delta(...) │ DOUBLE │ millisec │ │
395 │network...bytes │ U64 │ byte │ │
396 │delta(...) │ U64 │ byte │ │
397 │delta(...) / delta(...) │ DOUBLE │ byte/millisec │ /1048576 and │
398 │ │ │ │ *1000 │
399 │network...speed │ FLOAT │ Mbyte/sec │ │
400 │x │ DOUBLE │ Mbyte/sec │ │
401 └────────────────────────┴────────┴───────────────┴─────────────────┘
402 Expressions involving single instance selection or the matchinst func‐
403 tion must be associated with underlying metrics that have an instance
404 domain. These constructors make no sense for singular metrics.
405 Because semantic checking cannot be done at the time pmRegisterDerived
407 is called, errors found during semantic checking (when any subsequent
408 calls to pmNewContext(3) or pmReconnectContext(3) succeed) are reported
409 using pmprintf(3). These include:
410 Error: derived metric <name1>: operand: <name2>: <reason>
412 There was a problem calling pmLookupName(3) to identify the op‐
413 erand metric <name2> used in the definition of the derived met‐
414 ric <name1>.
415 Error: derived metric <name1>: operand (<name2> [<pmid2>]): <reason>
417 There was a problem calling pmLookupDesc(3) to identify the op‐
418 erand metric <name2> with PMID <pmid2> used in the definition of
419 the derived metric <name1>.
420 Semantic error: derived metric <name>: <operand> : <operand> Different
422 <metadata> for ternary operands
423 For a ternary expression, the ``true'' operand and the ``false''
424 operand must have exactly the same metadata, so type, semantics,
425 instance domain, and units (dimension and scale).
426 Semantic error: derived metric <name>: <operand> <op> <operand>: Dimen‐
428 sions are not the same
429 Operands must have the same units (dimension and scale) for each
430 of addition, subtraction, the relational operators and the bool‐
431 ean ``and'' or ``or'' operators.
432 Semantic error: derived metric <name>: <operand> <op> <operand>: Ille‐
434 gal operator for counter and non-counter
435 Only multiplication or division are allowed if the left operand
436 has the semantics of a counter and the right operand is not a
437 counter.
438 Semantic error: derived metric <name>: <operand> <op> <operand>: Ille‐
440 gal operator for counters
441 If both operands have the semantics of counter, only addition or
442 subtraction make sense, so multiplication and division are not
443 allowed.
444 Semantic error: derived metric <name>: <operand> <op> <operand>: Ille‐
446 gal operator for non-counter and counter
447 Only multiplication is allowed if the right operand has the se‐
448 mantics of a counter and the left operand is not a counter.
449 Semantic error: derived metric <metric> <expr> RESCALE <units>: Incom‐
451 patible dimensions
452 The parameters <expr> and <units> to the rescale function must
453 have the same dimension along the axes of Time, Space and Count.
454 Semantic error: derived metric <name>: Incorrect time dimension for op‐
456 erand
457 Rate conversion using the rate() function is only possible for
458 operand metrics with a Time dimension of 0 or 1 (see pm‐
459 LookupDesc(3)). If the operand metric's Time dimension is 0,
460 then the derived metrics has a value "per second" (Time dimen‐
461 sion of -1). If the operand metric's Time dimension is 1, then
462 the derived metrics has a value of time utilization (Time dimen‐
463 sion of 0).
464 Semantic error: derived metric <name>: <function>(<operand>): Non-
466 arithmetic operand for function
467 The unary functions are only defined if the operand has arith‐
468 metic type. Similarly the first argument to the rescale func‐
469 tion must be of arithmetic type.
470 Semantic error: derived metric <name>: <expr> ? ...: Non-arithmetic op‐
472 erand for ternary guard
473 The first expression for a ternary operator must have an arith‐
474 metic type.
475 Semantic error: derived metric <name>: ... - ...: Non-arithmetic oper‐
477 and for unary negation
478 Unary negation only makes sense if the following expression has
479 an arithmetic type.
480 Semantic error: derived metric <name>: <operand> <op> <operand>: Non-
482 arithmetic type for <left-or-right> operand
483 The binary arithmetic operators are only allowed with operands
484 with an arithmetic type (integer of various sizes and signed‐
485 ness, float or double).
486 Semantic error: derived metric <name>: <operand> <op> <operand>: Non-
488 counter and not dimensionless <left-or-right> operand
489 For multiplication or division or any of the relational opera‐
490 tors, if one of the operands has the semantics of a counter and
491 the other has the semantics of a non-counter (instantaneous or
492 discrete) then the non-counter operand must have no units (di‐
493 mension and scale).
494 Semantic error: derived metric <name>: <expr> ? <expr> : <expr>: Non-
496 scalar ternary guard with scalar expressions
497 If the ``true'' and ``false'' operands of a ternary expression
498 have a scalar value, then the ``guard'' expression must also
499 have a scalar value.
500 Semantic error: derived metric <name>: <expr> <op> <expr>: Operands
502 should have the same instance domain
503 For all of the binary operators (arithmetic and relational), if
504 both operands have non-scalar values, then they must be defined
505 over the same instance domain.
506
508 For the binary arithmetic operators, if either operand must be scaled
509 (e.g. convert bytes to Kbytes) then the result is promoted to
510 PM_TYPE_DOUBLE. Otherwise the type of the result is determined by the
511 types of the operands, as per the following table which is evaluated
512 from top to bottom until a match is found.
513 ┌─────────────────────────┬──────────┬────────────────┐
515 │ Operand Types │ Operator │ Result Type │
516 ├─────────────────────────┼──────────┼────────────────┤
517 │either is PM_TYPE_DOUBLE │ any │ PM_TYPE_DOUBLE │
518 ├─────────────────────────┼──────────┼────────────────┤
519 │any │ division │ PM_TYPE_DOUBLE │
520 ├─────────────────────────┼──────────┼────────────────┤
521 │either is PM_TYPE_FLOAT │ any │ PM_TYPE_FLOAT │
522 ├─────────────────────────┼──────────┼────────────────┤
523 │either is PM_TYPE_U64 │ any │ PM_TYPE_U64 │
524 ├─────────────────────────┼──────────┼────────────────┤
525 │either is PM_TYPE_64 │ any │ PM_TYPE_64 │
526 ├─────────────────────────┼──────────┼────────────────┤
527 │either is PM_TYPE_U32 │ any │ PM_TYPE_U32 │
528 ├─────────────────────────┼──────────┼────────────────┤
529 │otherwise (both are │ any │ PM_TYPE_32 │
530 │PM_TYPE_32) │ │ │
531 └─────────────────────────┴──────────┴────────────────┘
533 Derived metrics are not available when using pmFetchArchive(3) as this
534 routine does not use a target list of PMIDs that could be remapped (as
535 is done for pmFetch(3)).
536 There is no pmUnregisterDerived method, so once registered a derived
538 metric persists for the life of the application.
539
541 On success, pmRegisterDerived returns NULL.
542 If a syntactic error is found at the time of registration, the value
544 returned by pmRegisterDerived is a pointer into expr indicating where
545 the error was found. To identify what the error was, the application
546 should call pmDerivedErrStr(3) to retrieve the corresponding parser er‐
547 ror message.
548 pmRegisterDerivedMetric returns 0 and errmsg is undefined if the pars‐
550 ing is successful.
551 If the given expr does not conform to the required syntax pmRegister‐
553 DerivedMetric returns -1 and a dynamically allocated error message
554 string in errmsg. The error message is terminated with a newline and
555 includes both the input name and expr, along with an indicator of the
556 position at which the error was detected. e.g.
557 Error: pmRegisterDerivedMetric("my.disk.rates", ...) syntax
558 error
559 4rat(disk.dev.read)
560 ^
561 The position indicator line may be followed by an additional diagnostic
563 line describing the nature of the error, when available.
564 In the case of an error, the caller is responsible for calling free(3)
566 to release the space allocated for errmsg.
567
569 PCPIntro(1), free(3), pmAddDerived(3), pmAddDerivedMetric(3), PMAPI(3),
570 pmDerivedErrStr(3), pmFetch(3), pmLoadDerivedConfig(3), pmNewCon‐
571 text(3), pmprintf(3), pmReconnectContext(3) and PMNS(5).
572Performance Co-Pilot PMREGISTERDERIVED(3)