зарегистрировать глобальное производное имя и определение метрики (register a global derived metric name and definition)
Семантические проверки и правила (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 an arithmetic expression or a relational 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.
For an arithmetic expression, the dimension of each operand must
be the same. For a relational expression, the dimension of each
operand must be the same, except that numeric constants (with no
dimension) are allowed, e.g. in the expression
network.interface.in.drops > 0 .
To prevent arbitrary and non-sensical combinations some
restrictions apply to expressions that combine metrics with
counter semantics to produce a result with counter semantics.
For an arithmetic expression, if both operands have the semantics
of a counter, then only addition or subtraction is allowed, or if
the left operand is a counter and the right operand is not, then
only multiplication or division are allowed, or if the left
operand is not a counter and the right operand is a counter, then
only multiplication is allowed.
Because relational expressions use the current value only and
produce a result that is not a counter, either or both operands
of a relational expression may be counters.
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 │ │
└────────────────────────┴────────┴───────────────┴──────────────┘
Expressions involving single instance selection or the matchinst
function must be associated with underlying metrics that have an
instance domain. These constructors make no sense for singular
metrics.
Because semantic checking cannot be done at the time
pmRegisterDerived is called, errors found during semantic
checking (when any subsequent calls to pmNewContext(3) or
pmReconnectContext(3) succeed) 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> : <operand>
Different <metadata> for ternary operands
For a ternary expression, the ``true'' operand and the
``false'' operand must have exactly the same metadata, so
type, semantics, instance domain, and units (dimension and
scale).
Semantic error: derived metric <name>: <operand> <op> <operand>:
Dimensions are not the same
Operands must have the same units (dimension and scale)
for each of addition, subtraction, the relational
operators and the boolean ``and'' or ``or'' operators.
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 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 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 <metric> <expr> RESCALE <units>:
Incompatible dimensions
The parameters <expr> and <units> to the rescale function
must have the same dimension along the axes of Time, Space
and Count.
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).
Semantic error: derived metric <name>: <function>(<operand>):
Non-arithmetic operand for function
The unary functions are only defined if the operand has
arithmetic type. Similarly the first argument to the
rescale function must be of arithmetic type.
Semantic error: derived metric <name>: <expr> ? ...: Non-
arithmetic operand for ternary guard
The first expression for a ternary operator must have an
arithmetic type.
Semantic error: derived metric <name>: ... - ...: Non-arithmetic
operand for unary negation
Unary negation only makes sense if the following
expression has an arithmetic type.
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>: <operand> <op> <operand>:
Non-counter and not dimensionless <left-or-right> operand
For multiplication or division or any of the relational
operators, if one of the operands has the semantics of a
counter and the other has the semantics of a non-counter
(instantaneous or discrete) then the non-counter operand
must have no units (dimension and scale).
Semantic error: derived metric <name>: <expr> ? <expr> : <expr>:
Non-scalar ternary guard with scalar expressions
If the ``true'' and ``false'' operands of a ternary
expression have a scalar value, then the ``guard''
expression must also have a scalar value.
Semantic error: derived metric <name>: <expr> <op> <expr>:
Operands should have the same instance domain
For all of the binary operators (arithmetic and
relational), if both operands have non-scalar values, then
they must be defined over the same instance domain.
