Man Linux: Main Page and Category List

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.