Ubuntu Manpage: __pmControlLog - enable, disable or enquire about logging of performance metrics

Provided by: libpcp3-dev_6.2.0-1.1build4_amd64

NAME

       __pmControlLog - enable, disable or enquire about logging of performance metrics

C SYNOPSIS

       #include "pmapi.h"
       #include "libpcp.h"

       int __pmControlLog(int fd, const pmResult *request, int control, int state, int delta,
               pmResult **status);

       cc ... -lpcp

CAVEAT

       This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

       These interfaces are not part of the PCP APIs that are guaranteed to remain fixed  across  releases,  and
       they may not work, or may provide different semantics at some point in the future.

DESCRIPTION

__pmControlLog may be used to enable or disable the archiving 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 archive, 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 archive, 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 libpcp.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, 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).

DIAGNOSTICS