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