__pmcontrollog(3) — Linux manual page

NAME | C SYNOPSIS | CAVEAT | DESCRIPTION | NOTE | DIAGNOSTICS | SEE ALSO | COLOPHON

PMCONTROLLOG(3)         Library Functions Manual         PMCONTROLLOG(3)

NAME         top

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

C SYNOPSIS         top

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

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

       cc ... -lpcp

CAVEAT         top

       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         top

       __pmControlLog may be used to enable or disable the archiving for
       particular  performance metrics, as identified by the request pa‐
       rameter; see pmFetch(3) for an explanation of the pmResult struc‐
       ture.

       The application must have previously issued a  call  to  __pmCon‐
       nectLogger(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
       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 in‐
       stances of the metric should be used.   Enumeration  of  the  in‐
       stance  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 differ‐
       ent types of control may be used to ensure that some  performance
       metrics can be guaranteed to always be in the archive, 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 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  log‐
       ging  state  prior  to the request was mandatory (on or off), the
       state is changed to advisory off.  If the logging state  was  al‐
       ready advisory (either on or off), it remains unchanged.  If con‐
       trol  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 in‐
       terval 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 corre‐
       spondence  between  the elements of request and status.  For met‐
       rics 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  con‐
       trol, 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 re‐
       turns true if the metric was available from its source  the  last
       time  it  was  supposed to be logged, or false if it was unavail‐
       able; and PMLC_GET_DELTA returns the current logging interval for
       the metric (in milliseconds).  PMLC_MAX_DELTA defines the  great‐
       est 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 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         top

       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         top

       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.

SEE ALSO         top

       pmlc(1), pmlogger(1), PMAPI(3), pmFetch(3) and __pmConnectLog‐
       ger(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@groups.io.  This page was obtained from the project's
       upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot               PCP                   PMCONTROLLOG(3)

Pages that refer to this page: __pmconnectlogger(3)