1PMCONTROLLOG(3) Library Functions Manual PMCONTROLLOG(3)
2
6 __pmControlLog - enable, disable or enquire about logging of perfor‐
7 mance metrics
8
10 #include "pmapi.h"
11 #include "libpcp.h"
12 int __pmControlLog(int fd, const pmResult *request, int control,
14 int state, int delta, pmResult **status);
15 cc ... -lpcp
17
19 This documentation is intended for internal Performance Co-Pilot (PCP)
20 developer use.
21 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
27 __pmControlLog may be used to enable or disable the archive logging for
28 particular performance metrics, as identified by the request parameter;
29 see pmFetch(3) for an explanation of the pmResult structure.
30 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 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 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 log,
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 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 log, while others may be dynamically enabled or dis‐
62 abled as determined by the level and type of system activity.
63 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 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 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 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 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 log, and are never
110 logged again.
111 __pmControlLog returns zero on success.
113
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
122 PM_ERR_TOOSMALL
123 The number of metrics in request is less than one.
124 PM_ERR_VALUE
126 One or more of the pmValueSets in request had numval (the number
127 of instances) less than one.
128 EINVAL An invalid combination of control and state was specified, or
130 delta was negative.
131
133 pmlc(1), pmlogger(1), PMAPI(3), pmFetch(3) and __pmConnectLogger(3).
134Performance Co-Pilot PCP PMCONTROLLOG(3)