| PMREGISTERDERIVED(3) | Library Functions Manual | PMREGISTERDERIVED(3) |
pmRegisterDerived, pmRegisterDerivedMetric - register a global derived metric name and definition
#include <pcp/pmapi.h>
char *pmRegisterDerived(char *name, char *expr);
int pmRegisterDerivedMetric(char *name, char *expr, char
**errmsg);
cc ... -lpcp
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 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 expression defining how the values of name should be computed.
pmRegisterDerivedMetric is the exact functional equivalent to pmRegisterDerived except that it provides a simplified model of error 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 derived metrics to be determined.
If pmRegisterDerived is called after one or more PMAPI contexts has been opened, then the newly registered metrics will be avaiable 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 establised. 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 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:
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 prefix in the (unlikely) event that the external instance name contains a ``]''.
| 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, INSTANT or DISCRETE. |
| units | a specification of dimension and scale (together forming the units), in the syntax accepted by pmParseUnitsStr (3). |
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 matching
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)
The expression and the desired units must both have the same dimension, e.g Space=1, Time=-1 and Count=0 in the example above.
| 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. As a special 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 expression evaluation. |
| 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. |
For example, the following expression will have values for the
metric network.interface.in.bytes for all network
interfaces except the loopback and virtual bridge devices:
matchinst(!/^(lo)|(vbir)/, network.interface.in.bytes)
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 arbitrary 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 instance.
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:
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:
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 PM_TYPE_32) | any | PM_TYPE_32 |
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 derived metric persists for the life of the application.
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.
pmRegisterDerivedMetric returns 0 and errmsg is undefined if the parsing is successful.
If the given expr does not conform to the required syntax
pmRegisterDerivedMetric returns -1 and a dynamically allocated error
message 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 diagnostic line describing the nature of the error, when available.
In the case of an error, the caller is responsible for calling free(3) to release the space allocated for errmsg.
PCPIntro(1), free(3), pmAddDerived(3), pmAddDerivedMetric(3), PMAPI(3), pmDerivedErrStr(3), pmFetch(3), pmLoadDerivedConfig(3), pmNewContext(3), pmprintf(3), pmReconnectContext(3) and PMNS(5).
| Performance Co-Pilot |