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  de‐
       ferred  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 sin‐
       gular 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 oth‐
       ers 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 con‐
       trol 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  re‐
       quest  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 ap‐
       plied to all metrics and instances identified in request.

       The result argument status returns the current logging state for each of the nominated  performance  met‐
       rics.   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 deter‐
       mined 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 de‐
       fines 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  be‐
       tween  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.

Performance Co-Pilot                                   PCP                                       PMCONTROLLOG(3)