1PMCONTROLLOG(3)            Library Functions Manual            PMCONTROLLOG(3)
2
3
4

NAME

6       __pmControlLog  -  enable,  disable or enquire about logging of perfor‐
7       mance metrics
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11       #include <pcp/impl.h>
12
13       int __pmControlLog(int fd, const pmResult *request, int control, int state, int delta, pmResult **status)
14
15       cc ... -lpcp
16

DESCRIPTION

18       __pmControlLog may be used to enable or disable the archive logging for
19       particular performance metrics, as identified by the request parameter;
20       see pmFetch(3) for an explanation of the pmResult structure.
21
22       The application must have previously issued a call  to  __pmConnectLog‐
23       ger(3)  to  establish  a  control-port  connection  to  the pmlogger(1)
24       instance to whom the control request is to be  directed,  and  fd  (the
25       result from __pmConnectLogger(3)) identifies this connection.
26
27       Within  request,  only the details of the performance metrics and their
28       associated instances will be used, i.e.  the values of the metrics,  if
29       any,  will  be  ignored.  request would typically be constructed as the
30       result of an earlier call to pmFetch(3).  For metrics with  a  singular
31       value  (having  an  instance domain of PM_INDOM_NULL) the corresponding
32       pmValueSet should have the value one in the numval field and PM_IN_NULL
33       as the inst field of the single pmValue supplied.  If multiple explicit
34       instances are to be logged, the numval field of the  pmValueSet  should
35       contain  the  number  of  instances supplied and the inst fields of the
36       pmValue structures should contain specific instance identifiers  (which
37       may not have the reserved value PM_IN_NULL).
38
39       If  the numval field within any of the pmValueSet structures in request
40       has a value of zero, it indicates that all available instances  of  the
41       metric  should be used.  Enumeration of the instance domain is deferred
42       until the logger fetches the metric prior to writing  it  to  the  log,
43       rather   than  being  performed  when  the  __pmControlLog  request  is
44       received.  This is useful for metrics with instance domains that change
45       over  time.  It is an error to specify numval equal to zero if the cor‐
46       responding metric has a singular value (no instance domain).
47
48       There are several sorts of logging control available, namely  mandatory
49       or  advisory,  as defined by the control argument, and on, off or maybe
50       as defined by the state argument. These different types of control  may
51       be  used  to  ensure that some performance metrics can be guaranteed to
52       always be in the log, while others may be dynamically enabled  or  dis‐
53       abled as determined by the level and type of system activity.
54
55       The actual action to be performed is defined by the combination of con‐
56       trol and state as follows.  If control is PM_LOG_MANDATORY and state is
57       PM_LOG_ON, then logging is enabled.  If control is PM_LOG_MANDATORY and
58       state  is  PM_LOG_OFF,  then  logging  is  disabled.   If  control   is
59       PM_LOG_MANDATORY  and  state  is PM_LOG_MAYBE, then subsequent advisory
60       controls will be honored.  If the logging state prior  to  the  request
61       was  mandatory  (on  or off), the state is changed to advisory off.  If
62       the logging state was already advisory (either on or off),  it  remains
63       unchanged.   If  control is PM_LOG_ADVISORY and the last mandatory con‐
64       trol for the metric was PM_LOG_MAYBE, then logging is enabled  or  dis‐
65       abled   as   specified  by  the  state  argument,  i.e.   PM_LOG_ON  or
66       PM_LOG_OFF.  When the arguments state and control specify a request  to
67       change  the  logging  behavior,  the argument delta defines the logging
68       interval in milliseconds to be applied to  all  metrics  and  instances
69       identified in request.
70
71       The  result  argument status returns the current logging state for each
72       of the nominated performance metrics.  There is  a  1:1  correspondence
73       between  the  elements  of  request and status.  For metrics in request
74       that have pmValueSets with numval  equal  to  zero,  the  corresponding
75       pmValueSet  in  result will contain a value for each available instance
76       at the time of the call.  Each metric value in  status  will  have  the
77       current logging state encoded in it.  The detailed outcome of the oper‐
78       ation for each metric can be determined by comparing  these  values  to
79       that requested via control, state and delta.
80
81       Macros  defined  in  <pcp/impl.h>  may be used to extract the state and
82       logging interval from the returned metric values.  PMLC_GET_ON  returns
83       true  if  logging  is  on, or false if it is off; PMLC_GET_MAND returns
84       true  if  logging  is  mandatory,  or  false   if   it   is   advisory;
85       PMLC_GET_INLOG  returns  true  if  the  metric has been logged at least
86       once, or false otherwise; PMLC_GET_AVAIL returns true if the metric was
87       available  from  its source the last time it was supposed to be logged,
88       or false if it was unavailable; and PMLC_GET_DELTA returns the  current
89       logging  interval  for  the  metric  (in milliseconds).  PMLC_MAX_DELTA
90       defines the greatest delta that can be returned in  an  encoded  metric
91       value.
92
93       As  a special case, when control is PM_LOG_ENQUIRE, state and delta are
94       ignored, and status returns the current logging state of the  nominated
95       performance  metrics  (this  variant  makes  no  changes to the logging
96       state).
97
98       If the value of the logging interval  is  0,  either  for  delta  in  a
99       request  to change state to PM_LOG_ON, or encoded in the value returned
100       from PM_LOG_ENQUIRE, then this corresponds to the special ``once only''
101       logging  of  metrics that appear once in the archive log, and are never
102       logged again.
103
104       __pmControlLog returns zero on success.
105

SEE ALSO

107       pmlc(1), pmlogger(1), PMAPI(3), pmFetch(3) and __pmConnectLogger(3).
108

DIAGNOSTICS

110       PM_ERR_TOOSMALL
111              The number of metrics in request is less than one.
112
113       PM_ERR_VALUE
114              One or more of the pmValueSets in request had numval (the number
115              of instances) less than one.
116
117       EINVAL An  invalid  combination  of control and state was specified, or
118              delta was negative.
119
120
121
122Performance Co-Pilot                  SGI                      PMCONTROLLOG(3)
Impressum