NAME¶

pmGetDerivedControl, pmSetDerivedControl - get and set controls for derived metrics

C SYNOPSIS¶

#include <pcp/pmapi.h>

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

cc ... -lpcp

DESCRIPTION¶

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:

PCP_DERIVED_GLOBAL_LIMIT

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.

PCP_DERIVED_CONTEXT_LIMIT

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.

PCP_DERIVED_DEBUG_SYNTAX

Debug diagnostics during parsing of derived metric expression. The value 1 enables the diagnostics, 0 disables them. The initial value is 0.

PCP_DERIVED_DEBUG_SEMANTICS

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.

PCP_DERIVED_DEBUG_EVAL

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.

PCP_DERIVED_OPTION_NOVALUE

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)).

RETURN VALUES¶

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.

OTHER OPTIONS¶

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.

SEE ALSO¶

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