# __pmcontrollog

## 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_ para‐
           meter;  see  pmFetch(3)  for an explanation of the _pmResult_ struc‐
           ture.
    
           The application must have previously issued a call to **__pmConnect‐**
           **Logger**(3)  to  establish  a   control-port   connection   to   the
           pmlogger(1)  instance to whom the control request is to be direct‐
           ed, 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 con‐
           structed as the result of an earlier call to pmFetch(3).  For met‐
           rics  with  a  singular value (having an instance domain of **PM_IN‐**
           **DOM_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 num‐
           ber 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 _re‐_
           _quest_  has  a  value  of zero, it indicates that all available in‐
           stances 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 met‐
           rics 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  dis‐
           abled.   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 adviso‐
           ry (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 argu‐
           ments  _state_  and  _control_ specify a request to change the logging
           behavior, the argument _delta_ defines the logging interval in  mil‐
           liseconds 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  corre‐
           spondence between the elements of _request_ and _status._  For metrics
           in  _request_  that  have _pmValueSet_ s 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 de‐
           tailed 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** re‐
           turns 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  met‐
           ric was available from its source the last time it was supposed to
           be  logged, or false if it was unavailable; and **PMLC_GET_DELTA** re‐
           turns the current logging interval for the  metric  (in  millisec‐
           onds).   **PMLC_MAX_DELTA** defines the greatest _delta_ that can be re‐
           turned 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 re‐
           turned 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



           **PM_ERR_TOOSMALL**
                  The number of metrics in _request_ is less than one.
    
           **PM_ERR_VALUE**
                  One or more of the _pmValueSet_ s 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.
    


* * *