NAME
__pmControlLog - enable, disable or enquire about logging
of performance metrics
C SYNOPSIS
#include <pcp/pmapi.h>
#include <pcp/impl.h>
int __pmControlLog(int fd, const pmResult *request, int control, int state, int delta, pmResult **status)
cc ... -lpcp
DESCRIPTION
__pmControlLog may be used to enable or disable the
archive logging for particular performance metrics, as
identified by the request parameter; see pmFetch(3) for an
explanation of the pmResult structure.
The application must have previously issued a call to
__pmConnectLogger(3) to establish a control-port connec
tion to the pmlogger(1) instance to whom the control
request is to be directed, and fd (the result from
__pmConnectLogger(3)) identifies this connection.
Within request, only the details of the performance met
rics and their associated instances will be used, i.e.
the values of the metrics, if any, will be ignored.
request would typically be constructed as the result of an
earlier call to pmFetch(3). For metrics with a singular
value (having an instance domain of PM_INDOM_NULL) the
corresponding pmValueSet should have the value one in the
numval field and PM_IN_NULL as the inst field of the sin
gle pmValue supplied. If multiple explicit instances are
to be logged, the numval field of the pmValueSet should
contain the number of instances supplied and the inst
fields of the pmValue structures should contain specific
instance identifiers (which may not have the reserved
value PM_IN_NULL).
If the numval field within any of the pmValueSet struc
tures in request has a value of zero, it indicates that
all available instances of the metric should be used.
Enumeration of the instance domain is deferred until the
logger fetches the metric prior to writing it to the log,
rather than being performed when the __pmControlLog
request is received. This is useful for metrics with
instance domains that change over time. It is an error to
specify numval equal to zero if the corresponding metric
has a singular value (no instance domain).
There are several sorts of logging control available,
namely mandatory or advisory, as defined by the control
argument. These different types of control may be used to
ensure that some performance metrics can be guaranteed to
always be in the log, while others may be dynamically
enabled or disabled as determined by the level and type of
system activity.
The actual action to be performed is defined by the combi
nation of control and state as follows. If control is
PM_LOG_MANDATORY and state is PM_LOG_ON, then logging is
enabled. If control is PM_LOG_MANDATORY and state is
PM_LOG_OFF, then logging is disabled. If control is
PM_LOG_MANDATORY and state is PM_LOG_MAYBE, then subse
quent advisory controls will be honored. If the logging
state prior to the request was mandatory (on or off), the
state is changed to advisory off. If the logging state
was already advisory (either on or off), it remains
unchanged. If control is PM_LOG_ADVISORY and the last
mandatory control for the metric was PM_LOG_MAYBE, then
logging is enabled or disabled as specified by the state
argument, i.e. PM_LOG_ON or PM_LOG_OFF. When the argu
ments state and control specify a request to change the
logging behavior, the argument delta defines the logging
interval in milliseconds to be applied to all metrics and
instances identified in request.
The result argument status returns the current logging
state for each of the nominated performance metrics.
There is a 1:1 correspondence between the elements of
request and status. For metrics in request that have
pmValueSets with numval equal to zero, the corresponding
pmValueSet in result will contain a value for each avail
able instance at the time of the call. Each metric value
in status will have the current logging state encoded in
it. The detailed outcome of the operation for each metric
can be determined by comparing these values to that
requested via control, state and delta.
Macros defined in <pcp/impl.h> may be used to extract the
state and logging interval from the returned metric val
ues. PMLC_GET_ON returns true if logging is on, or false
if it is off; PMLC_GET_MAND returns true if logging is
mandatory, or false if it is advisory; PMLC_GET_INLOG
returns true if the metric has been logged at least once,
or false otherwise; PMLC_GET_AVAIL returns true if the
metric was available from its source the last time it was
supposed to be logged, or false if it was unavailable; and
PMLC_GET_DELTA returns the current logging interval for
the metric (in milliseconds). PMLC_MAX_DELTA defines the
greatest delta that can be returned in an encoded metric
value.
As a special case, when control is PM_LOG_ENQUIRE, state
and delta are ignored, and status returns the current
variant makes no changes to the logging state).
If the value of the logging interval is 0, either for
delta in a request to change state to PM_LOG_ON, or
encoded in the value returned from PM_LOG_ENQUIRE, then
this corresponds to the special ``once only'' logging of
metrics that appear once in the archive log, and are never
logged again.
__pmControlLog returns zero on success.
SEE ALSO
pmlc(1), pmlogger(1), PMAPI(3), pmFetch(3) and __pmCon
nectLogger(3).
DIAGNOSTICS
PM_ERR_TOOSMALL
The number of metrics in request is less than one.
PM_ERR_VALUE
One or more of the pmValueSets in request had num
val (the number of instances) less than one.
EINVAL An invalid combination of control and state was
specified, or delta was negative.
CAVEAT
On Irix this routine is part of the libpcp_dev.a, so your
compile lines should include -lpcp_dev and
-DHAVE_DEV_IN_LIBPCP where necessary.
Man(1) output converted with
man2html