Ubuntu Manpages

pmGetDerivedControl, pmSetDerivedControl

get and set controls for derived metrics

#include <pcp/pmapi.h>

int pmGetDerivedControl(int what, int *valuep);
int pmSetDerivedControl(int what, int value);

cc ... -lpcp

These routines may be used to influence the behaviour of the derived metric services that are activated for global derived metrics using pmRegisterDerived(3), pmRegisterDerivedMetric(3) and pmLoadDerivedConfig(3), or per-context derived metrics using pmAddDerived(3) and pmAddDerivedMetric(3).

The what argument selects a control or option, the value argument provides a value for pmSetDerivedControl and the valuep argument is used to return the value for pmGetDerivedControl.

The what argument has one of the following values:

The maximum number of global derived metrics that may be defined. The value should be greater than zero, or -1 (for no limit). The initial value is -1.
The maximum number of per-context derived metrics that may be defined. The value should be greater than zero, or -1 (for no limit). The initial value is -1.
Debug diagnostics during parsing of derived metric expression. The value 1 enables the diagnostics, 0 disables them. The initial value is 0.
Debug diagnostics for semantic checks during the binding of metrics in the derived metric expression to the available metrics in a new PMAPI context. The value 1 enables the diagnostics, 0 disables them. The initial value is 0.
Debug diagnostics when derived metrics are used in PMAPI operations like pmFetch(3), pmGetChildren(3), pmGetChildrenStatus(3), pmLookupDesc(3), pmLookupName(3), pmNameAll(3), pmNameID(3) and pmTraversePMNS(3). The value 1 enables the diagnostics, 0 disables them. The initial value is 0.
When a performance metric (used as an operand in a derived metric expression) is no available (e.g. missing from a PCP archive context or not provided by any PMDA for a host context), then the default behaviour is to mark the derived metric as undefined. If this option is set to 1 (the default is 0), then any metric that is not available is mapped to the novalue() constructor (refer to pmRegisterDerived(3) for details), which in essence means the metric is defined, but attempts to retrieve values via pmFetch(3) will return PM_ERR_VALUE (Missing metric value(s)).

Both routines return 0 on success, else a value less than 0 that can be decoded using pmErrStr(3).

Some overloading of error codes is needed to accommodate the unusual semantics of these routines, as described below.

Error Meaning
PM_ERR_NAME what is not one of the expected values
PM_ERR_ARG the value provided to pmSetDerivedControl is not within the acceptable range
PM_ERR_NOCONTEXT getting or setting PCP_DERIVED_CONTEXT_LIMIT only makes sense when there is a current PMAPI context
PM_ERR_AGAIN pmSetDerivedControl request would violate precedence rules (see below)

All of the controls and options that are exposed by pmSetDerivedControl can also be set in two other ways.

1.
Setting the PCP_DERIVED_CONTROL environment variable to a value of the form name=integer where name is one of the what macros described above, stripped of the PCP_DERIVED_ prefix, e.g. novalue=1. name is case insensitive and multiple specifications are allowed, separated by commas. No whitespace is allowed.
2.
Use of a #control line in a derived metric configuration file, where the text following the #control follows exactly the same rules as for the PCP_DERIVED_CONTROL environment variable described above.

Given these options can be specified in multiple ways, possibly with different values, the precedence rules are if PCP_DERIVED_CONTROL is set, then that value is honoured, else the most recently set value from #control or pmSetDerivedControl is used.

PCPIntro(1), pmAddDerived(3), pmAddDerivedMetric(3), PMAPI(3), pmErrStr(3), pmLoadDerivedConfig(3), pmRegisterDerived(3), pmRegisterDerivedMetric(3) and PMNS(5).