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.