Provided by: libpcp3-dev_3.10.8build1_amd64 
NAME
pmRegisterDerived - register a derived metric name and definition
C SYNOPSIS
#include <pcp/pmapi.h>
char *pmRegisterDerived(char *name, char *expr);
cc ... -lpcp
DESCRIPTION
Derived metrics provide a way of extending the Performance Metrics Name Space (PMNS) with
new metrics defined at the PCP client-side using arithmetic expressions over the existing
performance metrics.
Typical uses would be to aggregate a number of similar metrics to provide a higher-level
summary metric or to support the ``delta V over delta V'' class of metrics that are not
possible in the base data semantics of PCP. An example of the latter class would be the
average I/O size, defined as
delta(disk.dev.total_bytes) / delta(disk.dev.total)
where both of the disk.dev metrics are counters, and what is required is to to sample both
metrics, compute the difference between the current and previous values and then calculate
the ratio of these differences.
The arguments to pmRegisterDerived are the name of the new derived metric and expr is an
arithmetic expression defining how the values of name should be computed.
name should follow the syntactic rules for the names of performance metrics, namely one or
more components separated with a dot (``.''), and each component must begin with an
alphabetic followed by zero or more characters drawn from the alphabetics, numerics and
underscore (``_''). For more details, refer to PCPIntro(1) and pmns(5).
name must be unique across all derived metrics and should not match the name of any
regular metric in the PMNS. It is acceptable for name to share some part of its prefix
with an existing subtree of the PMNS, e.g. the average I/O size metric above could be
named disk.dev.avgsz which would place it amongst the other disk.dev metrics in the PMNS.
Alternatively, derived metrics could populate their own subtree of the PMNS, e.g. the
average I/O size metric above could be named my.summary.disk.avgsz.
The expression expr follows these syntactic rules:
* Terminal elements are either names of existing metrics or integer constants. Recursive
definitions are not allowed, so only the names of regular metrics (not other derived
metrics) may be used. Integer constants are constrained to the precision of 32-bit
unsigned integers.
* The usual binary arithmetic operators are supported, namely - addition (``+''),
subtraction (``-''), multiplication (``*'') and division (``/'') with the normal
precedence rules where multiplication and division have higher precedence than addition
and subtraction, so a+b*c is evaluated as a+(b*c)
* Parenthesis may be used for grouping.
* The following unary functions operate on a single performance metric and return one or
more values. For all functions (except count() and instant()), the type of the operand
metric must be arithmetic (integer of various sizes and signedness, float or double).
┌───────────┬────────────────────────────────────────────────────┐
│ Function │ Value │
├───────────┼────────────────────────────────────────────────────┤
│avg(x) │ A singular instance being the average value across │
│ │ all instances for the metric x. │
├───────────┼────────────────────────────────────────────────────┤
│count(x) │ A singular instance being the count of the number │
│ │ of instances for the metric x. │
├───────────┼────────────────────────────────────────────────────┤
│delta(x) │ Returns the difference in values for the metric x │
│ │ between one call to pmFetch(3) and the next. There │
│ │ is one value in the result for each instance that │
│ │ appears in both the current and the previous │
│ │ sample. │
├───────────┼────────────────────────────────────────────────────┤
│rate(x) │ Returns the difference in values for the metric x │
│ │ between one call to pmFetch(3) and the next │
│ │ divided by the elapsed time between the calls to │
│ │ pmFetch(3). The semantics of the derived metric │
│ │ are based on the semantics of the operand (x) with │
│ │ the dimension in the time domain decreased by one │
│ │ and scaling if required in the time utilization │
│ │ case where the operand is in units of time, and │
│ │ the derived metric is unitless. This mimics the │
│ │ rate conversion applied to counter metrics by │
│ │ tools such as pmval(1), pmie(1) and pmchart(1). │
│ │ There is one value in the result for each instance │
│ │ that appears in both the current and the previous │
│ │ sample. │
├───────────┼────────────────────────────────────────────────────┤
│instant(x) │ Returns the current value of the metric x, even it │
│ │ has the semantics of a counter, i.e. │
│ │ PM_SEM_COUNTER. The semantics of the derived │
│ │ metric are based on the semantics of the operand │
│ │ (x); if x has semantics PM_SEM_COUNTER, the │
│ │ semantics of instant(x) is PM_SEM_INSTANT, │
│ │ otherwise the semantics of the derived metric is │
│ │ the same as the semantics of the metric x. │
├───────────┼────────────────────────────────────────────────────┤
│max(x) │ A singular instance being the maximum value across │
│ │ all instances for the metric x. │
├───────────┼────────────────────────────────────────────────────┤
│min(x) │ A singular instance being the minimum value across │
│ │ all instances for the metric x. │
├───────────┼────────────────────────────────────────────────────┤
│sum(x) │ A singular instance being the sum of the values │
│ │ across all instances for the metric x. │
└───────────┴────────────────────────────────────────────────────┘
* White space is ignored.
Syntactic checking is performed at the time pmRegisterDerived is called, but semantic
checking is deferred until each new context is created with pmNewContext(3) or re-
established with pmReconnectContext(3), at which time the PMNS and metadata is available
to allow semantic checking and the metadata of the derived metrics to be established.
SEMANTIC CHECKS AND RULES
There are a number of conversions required to determine the metadata for a derived metric
and to ensure the semantics of the expressions are sound.
In a binary expression, if the semantics of both operands is not a counter (i.e.
PM_SEM_INSTANT or PM_SEM_DISCRETE) then the result will have semantics PM_SEM_INSTANT
unless both operands are PM_SEM_DISCRETE in which case the result is also PM_SEM_DISCRETE.
The mapping of the pmUnits of the metadata uses the following rules:
* If both operands have a dimension of COUNT and the scales are not the same, use the
larger scale and convert the values of the operand with the smaller scale.
* If both operands have a dimension of TIME and the scales are not the same, use the
larger scale and convert the values of the operand with the smaller scale.
* If both operands have a dimension of SPACE and the scales are not the same, use the
larger scale and convert the values of the operand with the smaller scale.
* For addition and subtraction all dimensions for each of the operands and result are
identical.
* For multiplication, the dimensions of the result are the sum of the dimensions of the
operands.
* For division, the dimensions of the result are the difference of the dimensions of the
operands.
Scale conversion involves division if the dimension is positive else multiplication if the
dimension is negative. If scale conversion is applied to either of the operands, the
result is promoted to type PM_TYPE_DOUBLE.
Putting all of this together in an example, consider the derived metric defined as
follows:
x = network.interface.speed - delta(network.interface.in.bytes) /
delta(sample.milliseconds)
The type, dimension and scale settings would propagate up the expression tree as follows.
┌────────────────────────┬────────┬───────────────────┬────────────────────┐
│ Expression │ Type │ Dimension & Scale │ Scale Factor(s) │
├────────────────────────┼────────┼───────────────────┼────────────────────┤
│sample.milliseconds │ DOUBLE │ millisec │ │
│delta(...) │ DOUBLE │ millisec │ │
│network...bytes │ U64 │ byte │ │
│delta(...) │ U64 │ byte │ │
│delta(...) / delta(...) │ DOUBLE │ byte/millisec │ /1048576 and *1000 │
│network...speed │ FLOAT │ Mbyte/sec │ │
│x │ DOUBLE │ Mbyte/sec │ │
└────────────────────────┴────────┴───────────────────┴────────────────────┘
Because semantic checking cannot be done at the time pmRegisterDerived is called, errors
found during semantic checking are reported using pmprintf(3). These include:
Error: derived metric <name1>: operand: <name2>: <reason>
There was a problem calling pmLookupName(3) to identify the operand metric <name2>
used in the definition of the derived metric <name1>.
Error: derived metric <name1>: operand (<name2> [<pmid2>]): <reason>
There was a problem calling pmLookupDesc(3) to identify the operand metric <name2>
with PMID <pmid2> used in the definition of the derived metric <name1>.
Semantic error: derived metric <name>: <operand> <op> <operand>: Illegal operator for
counters
If both operands have the semantics of counter, only addition or subtraction make
sense, so multiplication and division are not allowed.
Semantic error: derived metric <name>: <operand> <op> <operand>: Illegal operator for
counter and non-counter
Only multiplication or division are allowed if the left operand has the semantics
of a counter and the right operand is not a counter.
Semantic error: derived metric <name>: <operand> <op> <operand>: Illegal operator for non-
counter and counter
Only multiplication is allowed if the right operand has the semantics of a counter
and the left operand is not a counter.
Semantic error: derived metric <name>: <operand> <op> <operand>: Non-arithmetic type for
<left-or-right> operand
The binary arithmetic operators are only allowed with operands with an arithmetic
type (integer of various sizes and signedness, float or double).
Semantic error: derived metric <name>: <function>(<operand>): Non-arithmetic operand for
function
The unary functions are only defined if the operand has arithmetic type.
Semantic error: derived metric <name>: Incorrect time dimension for operand
Rate conversion using the rate() function is only possible for operand metrics with
a Time dimension of 0 or 1 (see pmLookupDesc(3)). If the operand metric's Time
dimension is 0, then the derived metrics has a value "per second" (Time dimension
of -1). If the operand metric's Time dimension is 1, then the derived metrics has
a value of time utilization (Time dimension of 0).
EXPRESSION EVALUATION
For the binary arithmetic operators, if either operand must be scaled (e.g. convert bytes
to Kbytes) then the result is promoted to PM_TYPE_DOUBLE. Otherwise the type of the
result is determined by the types of the operands, as per the following table which is
evaluated from top to bottom until a match is found.
┌─────────────────────────┬──────────┬────────────────┐
│ Operand Types │ Operator │ Result Type │
├─────────────────────────┼──────────┼────────────────┤
│either is PM_TYPE_DOUBLE │ any │ PM_TYPE_DOUBLE │
├─────────────────────────┼──────────┼────────────────┤
│any │ division │ PM_TYPE_DOUBLE │
├─────────────────────────┼──────────┼────────────────┤
│either is PM_TYPE_FLOAT │ any │ PM_TYPE_FLOAT │
├─────────────────────────┼──────────┼────────────────┤
│either is PM_TYPE_U64 │ any │ PM_TYPE_U64 │
├─────────────────────────┼──────────┼────────────────┤
│either is PM_TYPE_64 │ any │ PM_TYPE_64 │
├─────────────────────────┼──────────┼────────────────┤
│either is PM_TYPE_U32 │ any │ PM_TYPE_U32 │
├─────────────────────────┼──────────┼────────────────┤
│otherwise (both are │ any │ PM_TYPE_32 │
│PM_TYPE_32) │ │ │
└─────────────────────────┴──────────┴────────────────┘
CAVEATS
Unary negation is not supported, so the following expressions would be syntactically
incorrect, -3*abc and -this.number
Derived metrics are not available when using pmFetchArchive(3) as this routine does not
use a target list of PMIDs that could be remapped (as is done for pmFetch(3)).
pmRegisterDerived does not apply retrospectively to any open contexts, so the normal use
would be to make all calls to pmRegisterDerived (possibly via pmLoadDerivedConfig(3)) and
then call pmNewContext(3).
There is no pmUnregisterDerived method, so once registered a derived metric persists for
the life of the application.
DIAGNOSTICS
On success, pmRegisterDerived returns NULL.
If a syntactic error is found at the time of registration, the value returned by
pmRegisterDerived is a pointer into expr indicating where the error was found. To
identify what the error was, the application should call pmDerivedErrStr(3) to retrieve
the corresponding parser error message.
SEE ALSO
PCPIntro(1), PMAPI(3), pmDerivedErrStr(3), pmFetch(3), pmLoadDerivedConfig(3),
pmNewContext(3) and pmReconnectContext(3).