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 "pmapi.h"
11       #include "libpcp.h"
12
13       int __pmControlLog(int fd, const pmResult *request, int control,
14               int state, int delta, pmResult **status);
15
16       cc ... -lpcp
17

CAVEAT

19       This  documentation is intended for internal Performance Co-Pilot (PCP)
20       developer use.
21
22       These interfaces are not part of the PCP APIs that  are  guaranteed  to
23       remain  fixed  across  releases,  and they may not work, or may provide
24       different semantics at some point in the future.
25

DESCRIPTION

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

NOTE

115       This routine is not thread-safe as there is no serialization on the use
116       of the communication channel between the sending of the request and re‐
117       ceiving  the  reply.  It is assumed that the caller is single-threaded,
118       which is true for  the  only  current  user  of  this  routine,  namely
119       pmlc(1).
120

DIAGNOSTICS

122       PM_ERR_TOOSMALL
123              The number of metrics in request is less than one.
124
125       PM_ERR_VALUE
126              One or more of the pmValueSets in request had numval (the number
127              of instances) less than one.
128
129       EINVAL An invalid combination of control and state  was  specified,  or
130              delta was negative.
131

SEE ALSO

133       pmlc(1), pmlogger(1), PMAPI(3), pmFetch(3) and __pmConnectLogger(3).
134
135
136
137Performance Co-Pilot                  PCP                      PMCONTROLLOG(3)
Impressum