--- name: "pmregisterderived" section: "3" platform: "linux" package: "libpcp3-dev" version: "4.3.2+really4.3.1-0.1" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/pmRegisterDerived" --- # pmregisterderived(3) register a derived metric name and definition Part of [pmRegisterDerived(3)](/pmRegisterDerived/3.md). ## NAME **pmRegisterDerived**, **pmRegisterDerivedMetric** - register a derived metric name and definition ## C SYNOPSIS **#include \** **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 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)](/pmNewContext/3.md) or re-established with [**pmReconnectContext**(3)](/pmReconnectContext/3.md), at which time the PMNS and metadata is available to allow semantic checking and the metadata of the derived metrics to be determined. This means **pmRegisterDerived** does not apply retrospectively to any open PMAPI contexts, nor to any PMAPI contexts already open at the time **pmRegisterDerived** is called, so the normal use would be to make all calls to **pmRegisterDerived** (possibly via [**pmLoadDerivedConfig**(3)](/pmLoadDerivedConfig/3.md)) or **pmRegisterDerivedMetric** and then call [**pmNewContext**(3)](/pmNewContext/3.md). *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)](/PCPIntro/1.md) and [**pmns**(5)](/pmns/5.md). *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 numeric 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 floating point numbers. - \* 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)`. - \* Unary negation may be used, e.g. `-3*some.metric`. - \* C-style relational operators are supported, namely \`\`\<'', \`\`\<='', \`\`=='', \`\`\>='', \`\`\>'' and \`\`!=''. Relational expresssions 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 relational 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 expresssions return a value as a 32-bit unsigned 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||cb)||(c, stripped of the PM\_TYPE\_ prefix, so `32`, `U32`, `64`, `U64`, `FLOAT` or `DOUBLE`. | | `semantics` | one of the semantic types from \, 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)](/pmParseUnitsStr/3.md). | 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)` - \* 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)](/pmParseUnitsStr/3.md). For example:\ `rescale(network.interface.total.bytes, "Mbytes/hour")` `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.` - \* `The following unary functions operate on a single performance metric` `and return one or more values.` `For all functions (except` `count()`, `defined()` 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. 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)](/pmNewContext/3.md) or re-established with [**pmReconnectContext**(3)](/pmReconnectContext/3.md). 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)](/pmFetch/3.md) 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)](/pmFetch/3.md) and the next divided by the elapsed time between the calls to [**pmFetch**(3)](/pmFetch/3.md). 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)](/pmval/1.md), [**pmie**(1)](/pmie/1.md) and [**pmchart**(1)](/pmchart/1.md). 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. | - \* The `matchinst` function may be used to select a subset of the instances from an instance domain for a metric or expression. The function takes two arguments: - (a) A instance filter that consists of an optional negation operator \`\`!'' followed by a regular expression delimited by \`\`/'' characters. The regular expression follows the POSIX Extended Regular Expression syntax as described in [**regex**(3)](/regex/3.md). Backslashes may be used as escape prefixes, but double backslash is 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 expression 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 **except** 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 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. - \* Parenthesis may be used for explicit grouping. - \* 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 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 subraction 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)](/pmNewContext/3.md) or [**pmReconnectContext**(3)](/pmReconnectContext/3.md) succeed) are reported using [**pmprintf**(3)](/pmprintf/3.md). These include: - Error: derived metric \: operand: \: \ There was a problem calling [**pmLookupName**(3)](/pmLookupName/3.md) to identify the operand metric \ used in the definition of the derived metric \. - Error: derived metric \: operand (\ \[\\]): \ There was a problem calling [**pmLookupDesc**(3)](/pmLookupDesc/3.md) to identify the operand metric \ with PMID \ used in the definition of the derived metric \. - Semantic error: derived metric \: \ : \ Different \ 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 \: \ \ \: 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 \: \ \ \: 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 \: \ \ \: 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 \: \ \ \: 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 \ \ RESCALE \: Incompatible dimensions The parameters \ and \ to the `rescale` function must have the same dimension along the axes of Time, Space and Count. - Semantic error: derived metric \: 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)](/pmLookupDesc/3.md)). 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 \: \(\): 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 \: \ ? ...: Non-arithmetic operand for ternary guard The first expression for a ternary operator must have an arithmetic type. - Semantic error: derived metric \: ... - ...: Non-arithmetic operand for unary negation Unary negation only makes sense if the following expression has an arithmetic type. - Semantic error: derived metric \: \ \ \: Non-arithmetic type for \ 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 \: \ \ \: Non-counter and not dimensionless \ 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 \: \ ? \ : \: 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 \: \ \ \: 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. ## 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 PM\_TYPE\_32) | any | PM\_TYPE\_32 | ## CAVEATS Derived metrics are not available when using [**pmFetchArchive**(3)](/pmFetchArchive/3.md) as this routine does not use a target list of PMIDs that could be remapped (as is done for [**pmFetch**(3)](/pmFetch/3.md)). 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)](/pmDerivedErrStr/3.md) 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)](/free/3.md) to release the space allocated for *errmsg*. ## SEE ALSO [**PCPIntro**(1)](/PCPIntro/1.md), [**free**(3)](/free/3.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmDerivedErrStr**(3)](/pmDerivedErrStr/3.md), [**pmFetch**(3)](/pmFetch/3.md), [**pmLoadDerivedConfig**(3)](/pmLoadDerivedConfig/3.md), [**pmNewContext**(3)](/pmNewContext/3.md), [**pmprintf**(3)](/pmprintf/3.md) and [**pmReconnectContext**(3)](/pmReconnectContext/3.md).