Provided by: libpcp3-dev_3.10.8build1_amd64 
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 connection 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 metrics 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
single 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 structures 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, and on, off or maybe as defined by the state 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 combination 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 subsequent 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 arguments 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 available 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 values. 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 logging state of the nominated performance metrics (this 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.
NOTE
This routine is not thread-safe as there is no serialization on the use of the
communication channel between the sending of the request and receiving the reply. It is
assumed that the caller is single-threaded, which is true for the only current user of
this routine, namely pmlc(1).
SEE ALSO
pmlc(1), pmlogger(1), PMAPI(3), pmFetch(3) and __pmConnectLogger(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 numval (the number of instances) less
than one.
EINVAL An invalid combination of control and state was specified, or delta was negative.