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