# pmregisterderived

## NAME



           **pmRegisterDerived** , **pmRegisterDerivedMetric** - register a global
           derived metric name and definition
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **char *pmRegisterDerived(char ***_name_**, char ***_expr_**);**
           **int pmRegisterDerivedMetric(char ***_name_**, char ***_expr_**,**
                                       **char ****_errmsg_**);**
    
           **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 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
           value-a over delta value-b'' class of metrics that are not  possi‐
           ble  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  re‐
           quired  is  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 expression defining how the values of _name_
           should be computed.
    
           **pmRegisterDerivedMetric** is the exact functional equivalent to  **pm‐**
           **RegisterDerived** except that it provides a simplified model of er‐
           ror handling, where a formatted message is returned via the _errmsg_
           parameter.
    
           Syntactic checking is performed at the time  **pmRegisterDerived** is
           called,  but  semantic  checking  is deferred until each new PMAPI
           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  de‐
           rived metrics to be determined.
    
           If  **pmRegisterDerived** is  called after one or more PMAPI contexts
           has been opened, then the newly registered metrics will be  avail‐
           able  in  those  contexts, however the more normal use would be to
           make   all    calls    to    **pmRegisterDerived**(possibly    via
           pmLoadDerivedConfig(3))  or **pmRegisterDerivedMetric** before calling
           pmNewContext(3).
    
           All of the defined global derived metrics  are  available  in  all
           PMAPI contexts.
    
           It  is  also possible to define per-context derived metrics once a
           PMAPI context has been established.   These  derived  metrics  are
           private  to the context in which they are defined using the allied
           routines pmAddDerived(3) and pmAddDerivedMetric(3).
    
           _name_ should follow the syntactic rules for the  names  of  perfor‐
           mance  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 accept‐
           able 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 numer‐
             ic constants.  Recursive definitions are not allowed, so only
             the names of regular metrics (not other derived metrics) may be
             used. Numeric constants are either integers constrained to the
             precision of 32-bit unsigned integers or double precision float‐
             ing point numbers.
    
           • The usual binary arithmetic operators are supported, namely ad‐
             dition (``+''), subtraction (``-''), multiplication (``*'') and
             division (``/'') with the normal precedence rules where multi‐
             plication and division have higher precedence than addition and
             subtraction, so a+b*c is evaluated as a+(b*c).
    
           • Unary negation may be used, e.g.  -3*some.metric.
    
           • C-style relational operators are supported, namely ``<'',
             ``<='', ``=='', ``>='', ``>'' and ``!=''.  Relational expres‐
             sions return a value as a 32-bit unsigned number being 0 for
             false and 1 for true.  The expected operator precedence rules
             apply, so arithmetic operators have higher precedence than rela‐
             tional operators, and a-b>c+d is evaluated as (a-b)>(c+d).  All
             the relational operators have equal precedence, so the (slightly
             odd) expression involving consecutive relational operators
             a>b!=c is evaluated as (a>b)!=c.
    
           • C-style boolean operators are supported, namely and (``&&'') and
             or (``||'').  Boolean expressions return a value as a 32-bit un‐
             signed number being 0 for false and 1 for true.  The expected
             operator precedence rules apply, so relational operators have
             higher precedence than boolean operators, and a>b*c&&d<=e+f is
             evaluated as (a>(b*c))&&(d<=(e+f)).  Both the boolean operators
             have equal precedence, so the expression involving consecutive
             boolean operators a>=b||b>c&&d!=e||f>g is evaluated as
             (((a>=b)||(b>c))&&(d!=e))||(f>g).
    
           • Additionally, the ``!'' operator may be used to negate a boolean
             or relational expression, returning a value as a 32-bit unsigned
             number being 0 for false and 1 for true.  The expected operator
             precedence rules apply, so boolean (and relational) operators
             have higher precedence than boolean negation, and !a>b||c<d is
             evaluated as !((a>b)||(c<d)), while !a<b+c is evaluated as
             !(a<(b+c)).
    
           • C-style ternary conditional expressions are supported. In gener‐
             al terms the expression check ? foo : bar is evaluated as foo
             (the ``true'' operand) if check (the ``guard'') is true, else
             the expression evaluates to bar (the ``false'' operand).  Some
             special semantic rules apply to the ``guard'' expression and the
             other two operand expressions:
             (a) Each expression may involve a singular value or a set of
                 values (when the expression involves one or more metrics
                 with an instance domain).
             (b) **All** expressions with a set of values must be defined over
                 the **same** instance domain.
             (c) Both operand expressions must have the **same** metadata, so the
                 same metric type, semantics and units (dimension and scale).
             (d) The ``guard'' expression must have an arithmetic or rela‐
                 tional or boolean value, so that it can be evaluated as 0
                 for false, else true.
             (e) If the ``guard'' expression has a singular value and one or
                 more of the other operand expressions involves an instance
                 domain, the ``guard'' applies to all instances.
             (f) If the ``guard'' expression has a set of values and one or
                 more of the other operand expressions involves an instance
                 domain, the ``guard'' is evaluated once for each instance
                 (there must be one instance domain as per rule (b) above).
             (g) If one of the operand expressions has a singular value and
                 the other has a set of values, and the singular value is se‐
                 lected based on the evaluation of the ``guard'', then the
                 result is a set of values (all the same) with instance enu‐
                 meration being taken from the other operand expression. For
                 example in the expression: check ? foo : bar, if foo is an
                 expression with a singular value and bar is a set-valued ex‐
                 pression, then if check is true, then the result is a set of
                 values (all having the same value, foo) over the instance
                 domain of bar.
             (h) As a special case, either (but not both) of the expressions
                 foo or bar may be the special constructor novalue().  If no‐
                 value() needs to be evaluated, it will return no values.
                 The most common use of novalue() is in conjunction with de‐
                 fined() as in the following example:
                     mumble = defined(abc.def) ? count(abc.def) : novalue()
                 The metadata for novalue() is taken from the peer operand of
                 the : operator, making conditions (b) and (c) above trivial‐
                 ly true; if the peer operand cannot be evaluated, then the
                 default metadata for novalue() is a singular discrete inte‐
                 ger with no units, and conditions (b) and (c) are waived.
                 An extension of novalue() is novalue(<metadata>) where the
                 <metadata> can be specified using one or more parameters of
                 the form _tag=value_ or _tag=_ "_value_ " as described for the mk‐
                 const() constructor below, for example:
                     novalue(type=float, semantics=instant,
                     units="Kbytes/sec")
             (i) As an additional further case, if check is of the form de‐
                 fined(somemetric) then references to undefined metrics are
                 allowed in whichever of foo or bar is **not** required once the
                 existence if somemetric has been established.  This allows
                 uses of the form:
                     fumble = defined(new.metric) ? new.metric : old.metric
                 which is valid when new.metric is defined **and** when new.met‐
                 ric is **not** defined, although this does mean rules (b) and
                 (c) are relaxed in this case, which further means novalue()
                 may have no peer operand to provide metadata.
                 A generalization of this construct is supported for any
                 check that can be evaluated statically, so a boolean expres‐
                 sion involving defined() predicates, for example:
                     bar = !defined(a) || !defined(b) ? novalue() : a + b
    
           • Selection of a single instance can be specified by the construct
             ``[_instance_name_]'' which may be appended to a metric name or a
             parenthesized expression.  For example:
                 fw.bytes = network.interface.in.bytes[eth1] + \
                            network.interface.out.bytes[eth1]
             or (equivalently):
                 fw.bytes = (network.interface.in.bytes + \
                             network.interface.out.bytes)[eth1]
    
             All characters between the ``['' and ``]'' are considered to be
             part of the (external) instance name, so be careful to avoid any
             spurious white space.  A backslash may be used as an escape pre‐
             fix in the (unlikely) event that the external instance name con‐
             tains a ``]''.
    
           • Numeric constants can also be specified using the mkconst() con‐
             structor which takes a number of arguments: the first is a nu‐
             meric constant (either integer or floating point), then follow
             one or more parameters of the form _tag=value_ or _tag=_ "_value_ "
             where the allowed values of _tag_ and _value_ are as follows:
             ┌───────────┬──────────────────────────────────────────────────┐
             │    _tag_    │                      _value_                       │
             ├───────────┼──────────────────────────────────────────────────┤
             │ type      │ one of the numeric metric types from             │
             │           │ <pcp/pmapi.h>, stripped of the PM_TYPE_ prefix,  │
             │           │ so 32, U32, 64, U64, FLOAT or DOUBLE.            │
             ├───────────┼──────────────────────────────────────────────────┤
             │ semantics │ one of the semantic types from <pcp/pmapi.h>,    │
             │           │ stripped of the PM_SEM_ prefix, so COUNTER, IN‐  │
             │           │ STANT or DISCRETE.                               │
             ├───────────┼──────────────────────────────────────────────────┤
             │ units     │ a specification of dimension and scale (together │
             │           │ forming the units), in the syntax accepted by    │
             │           │ pmParseUnitsStr(3).                              │
             ├───────────┼──────────────────────────────────────────────────┤
             │ meta      │ a metric name and that metric provides the base  │
             │           │ metadata that may be modified by other parame‐   │
             │           │ ters                                             │
             └───────────┴──────────────────────────────────────────────────┘
    
             The _value_ may optionally be enclosed in double quotes, and may
             appear in any mix of upper and/or lower case.  The _tag_ must be
             in lower case as shown in the table above.
    
             This is most useful when the expression semantics require match‐
             ing type and/or semantics and/or units for operands, e.g.
                 idle = mem.util.free > mkconst(10485760, units=Kbyte)
                 avg_io_size = delta(disk.dev.total) == 0 ? \
                     mkconst(1.0, semantics=instant, units="kbyte / count") :
                 \
                     delta(disk.dev.total_bytes) / delta(disk.dev.total)
    
           • Expressions may be rescaled using the rescale function that
             takes two arguments.  The first is an arithmetic expression to
             be rescaled, and the second is the desired units after rescaling
             that is a string value in the syntax accepted by
             pmParseUnitsStr(3).  For example:
                 rescale(network.interface.total.bytes, "Mbytes/hour")
    
             The expression and the desired units must both have the same di‐
             mension, e.g Space=1, Time=-1 and Count=0 in the example above.
    
           • The following unary functions operate on a single performance
             metric and return one or more values.  For all functions (except
             count() and defined()), 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 num‐ │
             │            │ ber of instances for the metric x.  As a spe‐   │
             │            │ cial case, if fetching the metric x returns an  │
             │            │ error, then count(x) will be 0.                 │
             ├────────────┼─────────────────────────────────────────────────┤
             │ defined(x) │ A boolean value that is true (``1'') if the     │
             │            │ metric x is defined in the PMNS, else false     │
             │            │ (``0'').  The function is evaluated when a new  │
             │            │ PMAPI context is created with pmNewContext(3)   │
             │            │ or re-established with pmReconnectContext(3).   │
             │            │ So any subsequent changes to the PMNS after the │
             │            │ PMAPI context has been established will not     │
             │            │ change the value of this function in the ex‐    │
             │            │ pression evaluation.                            │
             ├────────────┼─────────────────────────────────────────────────┤
             │ 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.          │
             └────────────┴─────────────────────────────────────────────────┘
    
           • The following unary function returns the instantaneous value of
             an expression, not the rate-converted value that is the default
             for expressions with the semantics of PM_SEM_COUNTER.
             ┌───────────────┬──────────────────────────────────────────────┐
             │   Function    │                    Value                     │
             ├───────────────┼──────────────────────────────────────────────┤
             │ instant(expr) │ Returns the current value of the expression, │
             │               │ even it has the semantics of a counter, i.e. │
             │               │ PM_SEM_COUNTER.  The semantics of the de‐    │
             │               │ rived metric are based on the semantics of   │
             │               │ the expression expr; if expr has semantics   │
             │               │ PM_SEM_COUNTER, the semantics of instant(ex‐ │
             │               │ pr) is PM_SEM_INSTANT, otherwise the seman‐  │
             │               │ tics of the derived metric is the same as    │
             │               │ the semantics of expr.                       │
             └───────────────┴──────────────────────────────────────────────┘
    
           • The following unary functions return values computed from the
             value of an expression on consecutive samples, or pmFetch(3)
             calls.  The expression (expr below) may involve one or more met‐
             rics but must have an arithmetic value (integer of various sizes
             and signedness, float or double) for all instances.
    
             If expr is a set-valued expression then only those instances
             that appear in **both** samples will appear in the result.
             ┌─────────────┬────────────────────────────────────────────────┐
             │  Function   │                     Value                      │
             ├─────────────┼────────────────────────────────────────────────┤
             │ delta(expr) │ Returns the difference in values for the ex‐   │
             │             │ pression 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.  If the expression is │
             │             │ unsigned, then the type of the result is con‐  │
             │             │ verted to ensure as much precision as possible │
             │             │ can be retained, so if the expression has type │
             │             │ PM_TYPE_U32 then the result is of type         │
             │             │ PM_TYPE_64, else if the expression has type    │
             │             │ PM_TYPE_U64 then the result is of type         │
             │             │ PM_TYPE_DOUBLE.  Otherwise the type of the re‐ │
             │             │ sult is the same as the type of the expres‐    │
             │             │ sion.                                          │
             ├─────────────┼────────────────────────────────────────────────┤
             │ rate(expr)  │ Returns the difference in values for the ex‐   │
             │             │ pression 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 expression with the dimension in the **time** │
             │             │ domain decreased by one and scaling if re‐     │
             │             │ quired in the time utilization case where the  │
             │             │ operand is in units of time, and the derived   │
             │             │ metric is unitless.  There is one value in the │
             │             │ result for each instance that appears in both  │
             │             │ the current and the previous sample, except in │
             │             │ the case where the expression has the seman‐   │
             │             │ tics of a counter, i.e. PM_SEM_COUNTER, and    │
             │             │ current value of an instance is smaller than   │
             │             │ the previous value of the same instance then   │
             │             │ no value is returned for this instance (this   │
             │             │ corresponds to a ``counter wrap'' or a         │
             │             │ ``counter reset'').  These rules mimic the     │
             │             │ rate conversion applied to counter metrics by  │
             │             │ tools such as pmval(1), pmie(1) and            │
             │             │ pmchart(1).                                    │
             └─────────────┴────────────────────────────────────────────────┘
    
           • The matchinst function may be used to select a subset of the in‐
             stances from an instance domain for a metric or expression.  The
             function takes two arguments:
             (a) A instance filter that consists of an optional negation op‐
                 erator ``!'' followed by a regular expression delimited by
                 ``/'' characters.  The regular expression follows the POSIX
                 Extended Regular Expression syntax as described in regex(3).
                 A single backslash may be used to escape the regular expres‐
                 sion delimiter ``/'', but double backslashes are required to
                 escape any regular expression special characters, e.g. for
                 the (extremely unlikely) case of wanting to match instance
                 names like ``some*text/other[text]'' a regular expression of
                 the form /some\\*text\/other\\[text]/ would be required.  If
                 present, the negation operator reverses the sense of the
                 filtering, so all instances **not** matching the regular expres‐
                 sion will be selected.
             (b) A metric or expression that must be defined over an instance
                 domain.
    
             For example, the following expression will have values for the
             metric network.interface.in.bytes for all network interfaces **ex‐**
             **cept** the loopback and virtual bridge devices:
                 matchinst(!/^(lo)|(vbir)/, network.interface.in.bytes)
    
           • The scalar function may be used convert a metric or expression
             defined over an instance domain into a scalar value that can be
             used in other expressions.  For example:
                 net.in.bytes = scalar(network.interface.in.bytes[eth0]) + \
                            scalar(network.interface.in.bytes[eth1])
    
             The instance domain is removed from the metadata for the result
             and the instance identifier is removed from the value during
             fetching.
    
             If the metric or expression involves more than one instance then
             the result is formed by picking the first instance - this is ar‐
             bitrary and implies the scalar function should only be used for
             metrics or expressions that are expected to contain zero or one
             instances, e.g.  the construct ``[_instance_name_]'' or the
             matchinst function with a pattern that matches at most one in‐
             stance.
    
           • Parenthesis may be used for explicit grouping.
    
           • A line ending with ``\'' is treated as ``to be continued'' and
             the following line is appended after stripping the ``\'' and the
             embedded newline.
    
           • Lines beginning with ``#'' are treated as comments and ignored.
    
           • White space is ignored.
    


## SEMANTIC CHECKS AND RULES



           There are a number of conversions required to determine the meta‐
           data for a derived metric and to ensure the semantics of the ex‐
           pressions are sound.
    
           In an arithmetic expression or a relational expression, if the se‐
           mantics of both operands is not a counter (i.e. PM_SEM_INSTANT or
           PM_SEM_DISCRETE) then the result will have semantics PM_SEM_IN‐
           STANT 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.inter‐
           face.in.drops > 0 .
    
           To prevent arbitrary and non-sensical combinations some restric‐
           tions apply to expressions that combine metrics with counter se‐
           mantics to produce a result with counter semantics.  For an arith‐
           metic 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 multi‐
           plication is allowed.
    
           Because relational expressions use the current value only and pro‐
           duce 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 conver‐
           sion 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 ex‐
           pression tree as follows.
         ┌─────────────────────────┬────────┬───────────────┬─────────────────┐
         │       Expression        │  Type  │  Dimension &  │ Scale Factor(s) │
         │                         │        │  Scale        │                 │
         ├─────────────────────────┼────────┼───────────────┼─────────────────┤
         │ 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 **pmRegister‐**
           **Derived** is called, errors found during semantic checking (when any
           subsequent calls to pmNewContext(3) or pmReconnectContext(3) suc‐
           ceed) 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 de‐
                  rived metric <name1>.
    
           Error: derived metric <name1>: operand (<name2> [<pmid2>]): <rea‐
           son>
                  There was a problem calling pmLookupDesc(3) to identify the
                  operand metric <name2> with PMID <pmid2> used in the defin‐
                  ition of the derived metric <name1>.
    
           Semantic error: derived metric <name>: <operand> : <operand> Dif‐
           ferent <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 addi‐
                  tion or subtraction make sense, so multiplication and divi‐
                  sion 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 di‐
                  mension 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-arith‐
           metic 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 for <left-or-right> operand
                  For multiplication or division or any of the relational op‐
                  erators, 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 expres‐
                  sion 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 relation‐
                  al), if both operands have non-scalar values, then they
                  must be defined over the same instance domain.
    
           Semantic error: derived metric <name>: operand <dname>: Illegal
           nested derived metric
                  A derived metric (<dname>) cannot be nested (i.e. used) in
                  the definition of another derived metric (<name>).
    
           Semantic error: derived metric <name>: <expr> <op> <expr>: Illegal
           operator for non-counters
                  Metrics with counter semantics may be added or subtracted,
                  but <op> (division or multiplication) is not allowed.
    
           Semantic error: derived metric <name>: operand <bname>: Unknown
           metric for ternary expression
                  When a new context was established, the metric <bname> was
                  not in the PMNS of the new context and <bname> is a re‐
                  quired operand in the definition of the derived metric
                  <name>.
    


## 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)              │          │                │
               └──────────────────────────┴──────────┴────────────────┘
    


## PMIDs AND MASKING



           Within PCP each metric is assigned a unique Performance Metric
           Identifier (PMID) and internally a PMID is constructed from 3
           fields: the domain number (of the associated Performance Metrics
           Domain Agent, or PMDA), the cluster number and the item number.
           Derived metrics use the reserved domain number 511 and special
           PMIDs as described in the following table, where the PMID is shown
           as domain.cluster.item:
           ┌────────────────┬───────────────┬───────────────────────────────┐
           │ Derived Metric │ Starting PMID │          Description          │
           ├────────────────┼───────────────┼───────────────────────────────┤
           │ global         │ 511.0.1       │ Metrics are assigned          │
           │                │               │ _ascending_ PMIDs as they are   │
           │                │               │ registered via                │
           │                │               │ **pmRegisterDerived** ,            │
           │                │               │ **pmRegisterDerivedMetric** or    │
           │                │               │ pmLoadDerivedConfig(3).       │
           ├────────────────┼───────────────┼───────────────────────────────┤
           │ per-context    │ 511.2047.1023 │ Metrics are assigned          │
           │                │               │ _descending_ PMIDs as they are  │
           │                │               │ registered via                │
           │                │               │ pmAddDerived(3) or            │
           │                │               │ pmAddDerivedMetric(3).        │
           ├────────────────┼───────────────┼───────────────────────────────┤
           │ remapped       │ 511.c.i       │ When a derived metric is      │
           │                │               │ recorded in a PCP archive by  │
           │                │               │ pmlogger(1) or one of the     │
           │                │               │ related archive creation      │
           │                │               │ tools, the PMID of the        │
           │                │               │ derived metric is remapped in │
           │                │               │ the archive so that _c_ is the  │
           │                │               │ cluster of derived metric     │
           │                │               │ plus 2048, and i is the item  │
           │                │               │ of the derived metric.  For   │
           │                │               │ example, a derived metric     │
           │                │               │ with PMID 511.0.13 will have  │
           │                │               │ the remapped PMID 511.2048.13 │
           │                │               │ in an archive.  See           │
           │                │               │ pmlogger(1) for a discussion  │
           │                │               │ about adding derived metrics  │
           │                │               │ to a PCP archive.             │
           └────────────────┴───────────────┴───────────────────────────────┘
    
           For base metrics from a host or archive context, there is a re‐
           quirement that each metric name is unique.  But derived metrics
           require this restriction to be relaxed, so that the same metric
           name could associated with a base metric, and/or a per-context de‐
           rived metric, and/or a global metric.  This means that one or more
           of the metrics with the same name may be masked by other metrics
           of the same name.  The following table describes which metric will
           be used when one of these multiply-defined names is presented to
           the PMAPI.
         ┌─────────────┬─────────────────────────────────┬─────────────────────┐
         │             │         derived metric          │                     │
         │ base metric ├──────────┬─────────────┬────────┤    chosen metric    │
         │             │ remapped │ per-context │ global │                     │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ no          │ no       │ no          │ no     │ none; the metric is │
         │             │          │             │        │ undefined           │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ no          │ no       │ no          │ yes    │ global derived      │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ no          │ no       │ yes         │ no     │ per-context derived │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ no          │ no       │ yes         │ yes    │ per-context derived │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ no          │ yes      │ no          │ no     │ remapped            │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ no          │ yes      │ no          │ yes    │ remapped            │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ no          │ yes      │ yes         │ no     │ remapped            │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ no          │ yes      │ yes         │ yes    │ remapped            │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ yes         │ no       │ no          │ no     │ base metric         │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ yes         │ no       │ no          │ yes    │ base metric         │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ yes         │ no       │ yes         │ no     │ base metric         │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ yes         │ no       │ yes         │ yes    │ base metric         │
         ├─────────────┼──────────┼─────────────┼────────┼─────────────────────┤
         │ yes         │ yes      │ -           │ -      │ cannot happen; for  │
         │             │          │             │        │ any name there can  │
         │             │          │             │        │ be at most one of a │
         │             │          │             │        │ base metric or a    │
         │             │          │             │        │ remapped metric     │
         └─────────────┴──────────┴─────────────┴────────┴─────────────────────┘
    
           When masking happens, it is done silently.  Most PCP applications
           support **-Dderive** on the command line and this pmdbg(1) debug op‐
           tion will report derived metric operations (including masking) on
           stderr.
    


## CAVEATS



           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)).
    
           There is no **pmUnregisterDerived** method, so once registered a de‐
           rived 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_ indi‐
           cating **where** the error was found.  To identify **what** the error was,
           the application should call pmDerivedErrStr(3) to retrieve the
           corresponding parser error message.
    
           **pmRegisterDerivedMetric** returns 0 and _errmsg_ is undefined if the
           parsing is successful.
    
           If the given _expr_ does not conform to the required syntax **pmRegis‐**
           **terDerivedMetric** returns -1 and a dynamically allocated error mes‐
           sage string in _errmsg_.  The error message is terminated with a
           newline and includes both the input _name_ and _expr_ , along with an
           indicator of the position at which the error was detected.  e.g.
                     Error: pmRegisterDerivedMetric("my.disk.rates", ...)
                     syntax error
                     _4rat(disk.dev.read)_
                         _^_
    
           The position indicator line may be followed by an additional diag‐
           nostic line describing the nature of the error, when available.
    
           In the case of an error, the **pmRegisterDerivedMetric** caller is re‐
           sponsible for calling free(3) to release the space allocated for
           _errmsg_.
    


* * *