__pmcontrollog(3) — Linux manual page


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
       parameter; see pmFetch(3) for an explanation of the pmResult

       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 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 metrics 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
       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 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
       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, 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

              The number of metrics in request is less than one.

              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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information 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 2023-12-22.
       (At that time, the date of the most recent commit that was found
       in the repository was 2023-12-16.)  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

Performance Co-Pilot               PCP                   PMCONTROLLOG(3)

Pages that refer to this page: __pmconnectlogger(3)